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COURSE DESCRIPTION 
FJJ5C PL/I Programming with Multics Subroutines 



Duration: Five Days 

Intended For: Advanced Multics PL/I programmers who need to use Multics 
subroutines to perform I/O, manipulate files in the 
storage system, and/ or write commands and active 
functions . 

Synopsis: This course introduces the student to the system 

subroutine repertoire to include subroutines that: 
create, delete, develop pointers to, and return status 
information about storage system entities (hcs ); perform 
stream and record I/O to files and devices via I/O 
switches ( iox_ ) ; enable command and active function 
procedures to properly interface to the standard command 
processing environment ( cu_) . Interactive workshops 
are included to reinforce the material presented. 

Objectives: Upon completion of this course, the student should be 

able to: write PL/I programs containing calls to system 
subroutines which: 

1. Create, destroy, and obtain status information on 
segments, directories, and links. 

2. Address and manipulate data directly in the virtual 
mernorv (without in n ut/out n, jt statements^ 

3. Interface directly with the Multics I/O System ( ioa , 
iox_) . " 

4. Implement "system standard" commands and active 
functions . 

Prerequisites: Advanced Multics PL/I Programming (F15B) or equivalent 
experience. 
" J'.' : :; '■ . '.; " « 

Major Topics: Advanced Use of Based Variables 

Subroutine Interfaces to the Storage System 

and ACL 
Multics Implementation of Condition Handling 
The Multics I/O System 
Writing Commands and Active Functions 
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STUDENT BACKGROUND 
PL/I Programming with Multics Subroutines (F15C) 



NAME: PHONE: 
TITLE: 



COMPANY ADDRESS: 



MANAGER: OFFICE PHONE: 



INSTRUCTOR'S NAME: 



1. Do you meet the prerequisite as stated in the "Course Description" 
of the student text? If yes, check "a" or "b". 
If no, check "c" or "d". 

a C ] Prerequisite satisfied by attending course indicated in "Course 
Description" . 



c [ ] Elected or instructed to attend course anyway, 
d [ ] Was not aware of prerequisite. 



2. What related Honeywell courses have you attended? Furnish dates 
and instructors if possible. 



(PLEASE TURN OVER) 
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STUDENT BACKGROUND 
PL/I Programming with Multics Subroutines (F15C) 



3. Check the boxes for which you have any related experience. (May 
be other than Honeywell's) 



[ 3 PL1 
[ ] JCL 
C ] NPS 



[ ] COBOL 

[ ] OPERATIONS 

[ ] GRTS 



[ ] FORTRAN 
[ -3 GCOS 
[ ] CP6 



[ ] ASSEMBLY 
[ ] MULTICS 
[ ] OTHER 



4. Detail any experience you have had which is related to the 
material in this course. 



5. Objectives for attending this course (May check more than one) 
[ ] Require information to provide support for a system 
[ ] To maintain an awareness of this product 
[ 3 To evaluate or compare its potentials 
[ 3 Required to use or implement 
[ ] Need update from a previous release 
[ 3 Require a refresher 
C 3 Other : ^ - 
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HONEYWELL MARKETING EDUCATION 
COURSE AND INSTRUCTOR EVALUATION FORM 



INSTRUCTOR 
COURSE 
START DATE 
LOCATION 



STUDENT NAME (OPTIONAL) 



In the interest of developing training courses of high quality, 
and then improving on that base, we would like you to complete 
this questionnaire. Your information will aid us in making 
future revisions and improvements to this course. Both the 
instructor and his/her manager will review these responses. 

Please complete the form and return it to the instructor 
upon the completion of the course. In questions 1 through 
14, check the appropriate box and feel free to include additional 
comments. Attach additional sheets if you need more room 
for comments. Be objective and 'concrete' in your comments 
— be critical when criticism is appropriate. 
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TOPIC I 
Review of PL/I Attributes 



Page 

Classification of Attributes 1-1 

Usage Examples of Selected Attributes 1-2 

Aggregate Descriptors 1-7 
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Topic I REVIEW OF PL/1 ATTRIBUTES Topic I 

OBJECTIVES! 

Upon completion of this topic? students should be able to: 



1. Declare variables in PL/1 using full ranse of variable 
attributes. 



2. Determine which instance of a variable is being referenced at 
any given point in a program. 



3. Manipulate storage aggregates (arrays and structures) 

4. Write and use external procedures. 



5. Set up the proper entry declarations to use external 
procedures. 
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CLASSIFICATION OF ATTRIBUTES 



A REVIEW LIST OF ATTRIBUTES. STARRED ATTRIBUTES ARE COVERED IN 
DETAIL IN TOPICS 2, 3 AND 4. THIS CHAPTER PRESENTS USAGE EXAMPLES 
TO REVIEW/ CLARIFY SOME OF THE NON-STARRED ATTRIBUTES 



storage description 
storage type 
data type 

computational 
arithmetic 

mode : real complex 
scale : fixed float 
base : binary decimal 
precision : precision(p,q) 
string 

string type : character(n) bit(n) picture" ps" 
variability : varying nonvarying 
non - computational 
address 

statement : label entry format 
data 

locator : pointer* offset* 
TTTe l file 
area : area(n)* 
aggregate type 

array : dimension(bp, . . .) 
structure : structure member 
alignment : aligned unaligned 
management class 
storage class 

allocation : automatic static controlled* based(lq)* 
sharing : based(lq)* defined(r)* position(i)* parameter 
scope : internal external 
category : variable constant 
initial : initial (x,...) 
usage description 

entry : entry(d, . . .) returns(d, . . .) options( variable) 

offset : offset(a)* 

file"~constant 

operation : input output update 
organization 

stream : stream print environment interactive) 
record : record sequential direct keyed 
environment stringvalue) 
non - valued names 

compile time : like r 

intrinsic names: builtin condition* 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 



• ARITHMETIC DATA TYPES 



del x real fixed binary precision (17,0) aligned; 



del x; /• SAME AS PREVIOUS DECLARATION */ 



Q del salary float decimal (6); 



STRING DATA TYPES 



Q del string_1 char(4) init ("ABC"); 



D del string_2 chard) varying init ("ABC); 



string_1 



string_2 



I * I . 


C i 




Ue*«e«*s«a«««eee«o*e»«e9**«»WI ! 


A 


B ' 


C 


/ / / 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 



• STATEMENT LABEL PREFIX (DECLARED BY USAGE, NOT IN FORMAL DECLARATION) 



continue_1 : x = x + 1 ; 



/* label internal constant */ 



Q output 1: format ( a(9) ,f (6 ,2)) ; /* format internal constant */ 



prog_1 : proc; 



/* entry constant */ 



fl alternate: entry (a,b); 



/* entry constant */ 



# ALIGNMENT 



fl del string char(4) aligned; /* DEFAULT IS unaligned */ 



del number fixed bin unaligned; /* DEFAULT IS aligned */ 



• STATIC VS. AUTOMATIC 



del a init(O); 

del b init(O) static; 



/* automatic BY DEFAULT »/ 



as a + 1 ; 
b = b + 1; 
put skip list ( a,b) ; 



Not To Be Reproduced 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 



• AGGREGATES 



Q ARRAY 



del array_1 (10); 

del array~2 (-6:4); 

del array~3 (10,3); 

del array~4 dimension (5); 



STRUCTURE 

Q del 01 x structure, 

02 y char(8) member, 

02 z fixed bin(35) member; 

del 01 x, 02 y char(8), 02 z fixed bin(35); 

LIKE ATTRIBUTE 

Q del 1 record_1 , 

2 employee info , 
3 name cEar( 10) , 
3 salary fixed dec(10,2); 

D del 1 record_2 like record_1 ; 

D del 1 employee like record_1 .employee_info .name; 



PARAMETER 



D sub 1 : Droc ( a.b) : 



del a char(3) parameter; 

del b ehar(6); /* parameter ATTRIBUTE USUALLY OMITTED »/ 
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• USAGE EXAMPLES OF SELECTED ATTRIBUTES 



$ SCOPE OF VARIABLES 



D A: proc; /* SOURCE SEGMENT A.pll */' 

del x external; 4- ^f(C bv &&rijj\k"&'/ 
del y; / \ i ■ 



B: proc; 
del x; 



end B; 
end A; 



D C: proc; /» SOURCE SEGMENT C.pll */ 

del x external; 

end C; 

D D: proc; /* SOURCE SEGMENT D.pll */ 

del x; 

del y; 

• 
« 

end D; 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 



• VARIABLE VS. CONSTANT 



D del x internal static init (125) options (constant); 
del (file 1, file_2) file; 
del file_out file variable; 

file_out s file 2; 

put file (file_out) list ("Test line"); 



D TYPES OF IDENTIFIERS THAT ARE USUALLY USED AS CONSTANTS, BUT MAY 
BE DECLARED AND USED AS VARIABLES: label, entry, format, file 



• INITIALIZATION 



del array 1(5) init(1 ,2,3,4,5); 

del array"2(5) init( 1 ,2,(3)*) ; /• LAST 3 ELEMENTS UNDEFINED */ 
del array"3(3,2) init( 1 ,2,3,4,5,6); 



• ENVIRONMENT ATTRIBUTES 



open file (sysprint) stream output environment (interactive); 

put list ("line 1»); /• LINEFEED ADDED AT END AUTOMATICALLY »/ 
put list ("line 2") ; 



D del line char(150) varying; 

J_1 -4-....— «1 ~ <•* 1 -. . 

UWX QUI COil AXJ.7 4. i-U C , 

open file ( stream_file) environment ( stringvalue) record input 
title ( w record_stream__ user_input") ; 

read file ( stream_file) into (line); 

/» MAKES POSSIBLE TAKING ENTIRE LINE FROM TERMINAL WITH EMBEDDED 
BLANKS WITHOUT USING QUOTES */ 
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AGGREGATE DESCRIPTORS 



# DESCRIPTORS DESCRIBE THE DATA TYPE AND LAYOUT OF AN IDENTIFIER WITHOUT 
REFERENCE TO ANY VARIABLE NAMES OR IDENTIFIERS 



DESCRIPTORS ARE USED IN "PARAMETER DESCRIPTOR" LISTS, AND IN "RETURNS 
DESCRIPTOR" LISTS 



I EXAMPLES 

B declare foo$bar entry (fixed bin, ptr , char(*)); 

i declare how_many entry (fixed bin) returns (fixed dec(3,0)); 
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AGGREGATE DESCRIPTORS 

• DESCRIPTORS ARE FORMED FOR AGGREGATES AS FOLLOWS: 

ARRAY DESCRIPTORS 

D ARE DERIVED BY ELIMINATING THE IDENTIFIER FROM THE DECLARATION 

D THE ARRAY BOUNDS MAY BE PRECEDED BY THE 'dimension 1 OR 'dim' 
KEYWORD, OR THE KEYWORD MAY BE OMITTED IF THE ARRAY BOUNDS 
PRECEDE THE DATA TYPE 

EXAMPLES 

I del X(12,3) fixed dec(7); 

del getjt entry ((12,3) fixed dec(7)); 

fl del returnJC entryO returns (dim(12,3) fixed dec(7)); 

STRUCTURE DESCRIPTORS 

B ARE DERIVED FROM THE DECLARATION AS FOLLOWS: 
D ELIMINATING ALL IDENTIFIERS 
NORMALIZING THE LEVEL NUMBERS 

fl THE KEYWORDS 'structure' AND 'member' MAY BE OMITTED FROM THE 
DESCRIPTORS 
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AGGREGATE DESCRIPTORS 



D EXAMPLE 



del 1 A aligned, 

2 C(3) fixed bin, 

2 F ptr; 

fl del get_A entry (1 structure aligned, 2 dim(3) fixed bin 

member, 2 ptr member); 

Q del returns A entry () returns (1 aligned, 2 (3) fixed bin, 

2 ptr); 

fl del get_A entry (1 like A); 

fl del returns_A entry () returns (1 like A); 
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(End Of Topic) 



1. Considering the stated objectives of this course, rate the overall 
length of the course. 

CAN'T TOO ABOUT TOO 

JUDGE SHORT RIGHT LONG 

CO I 1 I 2 ■ 3 I I I B ' I I 7 I a I q I 

COMMENTS 



2. Considering the objectives, rate the technical level at which the 
course was taught. 

NOT 
CAN'T TECH ABOUT TOO 

JUDGE ENOUGH RIGHT TECH 

COMMENTS 



3. Considering the objectives, rate the emphasis placed on the more 
important topics. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

m t 1 I 2 I g I 4 I 5 I I 1 7 I A I Q 1 

COMMENTS 



4. Rate the sequence in which the topics were presented. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

CO f i i ^ t 3 | i | i | Q | i i i m 

COMMENTS 
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5. Rate the format and quality of the learning materials (slides, 
student handbooks, supplementary handouts, etc.). 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

IT- 1 I 1 I 2 I I \ . \ , I . \ l - » B I qn 

COMMENTS _____ 



6. Rate the amount of time given for the completion of the workshops. 

TOO T 00 

CAN'T LITTLE ABOUT MUCH 

JUDGE TIME RIGHT TIME 

1—0-1 I 3 » s I 3 1 . 1 I ' h I ; I k 1 q ' 



COMMENTS 



7. Rate the workshops* ability to relate back to and reinforce the 
material presented. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

1 — 5 — 1 1 1 1 . I ^ I . » _ I - I V 1 1 ^£3 

COMMENTS 



8. Rate the physical condition of the classroom (space available, 
temperature, lighting, etc.). 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

I— Q-1 1 1 I 2 I ? 1 J» I s I *, I v I tt 1 q I 

COMMENTS 
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9. Hate the physical condition of the lab or workshop room, (systems 
configuration, space available, learning tools, terminals, tables, 
etc.) . 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

1ZQ I 1 i 2 i 3 i k i i i i i 7 i i | n 

COMMENTS 



10. Rate your instructor' s demonstrated knowledge of the course material. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 



IZO II |2 l S|J4iq|&i7lft|q-I 

COMMENTS 



11. Rate your instructor's ability to convey the technical aspects of 
the various topics. 

CAN'T 



JUDGE 


POOR 












GOOD 








EXCELLENT 


1 1 


1 1 1 


2 


1 


\ 


1 


k 


1 <5 1 


6 


1 


7 


1 A 1 Q 1 


COMMENTS 



12. Rate the classroom and workshop assistance given you by your 
instructor. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

COMMENTS 
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13. Rate the instructor's ability to create an environment in which 

you felt free to ask questions. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

I i l1I2t^l4l5l6i7t£SI3> 

COMMENTS 



14. Rate the relevance of the skills learned in the course with respect 
to your job or further training. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

OZI I 3 ' I ' I I 5 I 5 I 5 ' I ' S ' t-1 

COMMENTS 



15. What did you like most about this course? 



16. What did you like least about this course? 
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17. Other comments please: 



18. 



Of the following job categories, check the ones which most nearly 
represent the bulk of your experience, and to the right of your 
responses indicate the number of years you have acted in that 
capacity. 



Applications Programmer. . . . 
Field Engineering Analyst. . . 

Manager . 

Marketing Analyst 

Salesperson, 

Secretary 

Systems Analyst 

Systems Programmer 

Other 



years 
( years 
years 
years 
years 
( years 
years 
years 
years 



Please give "other" title 
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TOPIC II 
PL/I Storage Management 
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Topic II PL/1 STORAGE MANAGEMENT Topic II 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 



1. Allocate and free controlled variables to implement a stack 
or a variable-extent data item such as a strins or array. 



2. Use defined variables to chanse the interpretation of a 
particular area of storage. 



3. Manipulate cross-sections of arrays usina "isub"-def ined 
variables. 
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DECLARING PL/I VARIABLES 

THE DECLARATION OF AN IDENTIFIER IS USUALLY DIVIDED INTO TWO PARTS 

THE STORAGE TYPE 

Q DESCRIBES THE TYPE OF VALUES WHICH CAN BE ACCOMMODATED 

D DESCRIBES THE AMOUNT AND INTERPRETATION OF STORAGE GENERATED 

2 THE STORAGE MANAGEMENT CLASS 

D SPECIFIES VARIOUS INFORMATION ABOUT THE HANDLING OF THE STORAGE 
GENERATED FOR THE IDENTIFIER INCLUDING 

D THE ALLOCATION AND FREEING MECHANISM TO BE USED 

Q THE LOCATION OF THE STORAGE TO BE GENERATED 

11 INITIALIZATION OF STORAGE 

1 AN EXAMPLE 

i del x real fixed binary(1Q,Q) automatic variable init(5); 
D 'real fixed binary( 10 ,0) • IS THE STORAGE TYPE 
D 'automatic variable init(5)' IS THE STORAGE MANAGEMENT CLASS 
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DEFINING THE PL/I STORAGE MANAGEMENT CLASS 

• FOUR ATTRIBUTES SPECIFY THE STORAGE MANAGEMENT CLASS 

1 THE 'usage category' ATTRIBUTE 

D DESCRIBES HOW THE STORAGE IS USED 

VALUES ARE 'variable' AND 'constant' 

D MOST OFTEN, THE USAGE CATEGORY ATTRIBUTE IS OMITTED 

THE 'scope' ATTRIBUTE 

D PARTIALLY DETERMINES THE REGION IN WHICH THE STORAGE IS ALLOCATED 
Q AFFECTS THE ACCESSIBILITY OF THE IDENTIFIER 
D VALUES ARE 'internal' AND 'external 1 

D THE 'storage class' ATTRIBUTE 

D SELECTS THE MECHANISM TO BE USED FOR THE ALLOCATION AND FREEING 
OF THE STORAGE GENERATED 



D VALUES ARE 'automatic' , 'static' , • controlled' , 'based', 
'defined' AND ! parameter ■ 



THE 'initial value' ATTRIBUTE 

WHEN PRESENT, SPECIFIES A VALUE TO BE ASSIGNED TO THE IDENTIFIER 
WHEN IT IS ALLOCATED 

VALUE IS 'initial (value list)' 
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DEFINING THE PL/I STORAGE MANAGEMENT CLASS 
ABBREVIATIONS AND DEFAULTS 



VALID ABBREVIATIONS FOR STORAGE MANAGEMENT ATTRIBUTES 



ATTRIBUTE 



ABBREVIATION 



internal 

external 

automatic 

controlled 

defined 

parameter 

initial 



int 

ext 

auto 

ctl 

def 

param 

init 



• STORAGE MANAGEMENT DEFAULT VALUES 



OMITTED ATTRIBUTE 



DEFAULT VALUE 



usage category 



'variable' 

(exception : 'constant' if the data 
type is 'entry* or 'file') 



scope 



' internal' 

(exception : 'external ' if the data 
type is 'entry' or 'file') 



storage class 



* automatic' 

(exception: 'static' if the 
•external' attribute is 
present or implied) 



D NOTE: THE DEFAULTS APPLY TO IDENTIFIERS DECLARED IN A FORMAL 
DECLARATION STATEMENT. FOR EXAMPLE: 



D A LABEL FORMALLY DECLARED IS A variable BY DEFAULT 



D A LABEL DECLARED BY USAGE AS A LABEL PREFIX IS A constant 



Not To Be Reproduced 



2-3 



F15C 



'controlled' STORAGE CLASS 



CHARACTERISTICS 



• 'controlled' STORAGE ALLOWS THE PROGRAMMER TO CONTROL THE GENERATION 
OF STORAGE FOR A VARIABLE 



D IT IS DRIVEN BY EXPLICIT PROGRAM STATEMENTS 



D STORAGE IS ALLOCATED BY THE 'allocate' STATEMENT, AND FREED BY 
THE 'free' STATEMENT 



A 'controlled' VARIABLE IS THEREFORE AVAILABLE FOR WHATEVER PORTION 
OF EXECUTION OF THE PROGRAM THE PROGRAMMER DESIRES 



A SMALL CONTROL BLOCK ASSOCIATED WITH THE 'controlled' VARIABLE 
IS USED TO LOCATE ITS CURRENTLY ALLOCATED STORAGE 



D 'controlled' VARIABLES CAN BE "STACKED" 



THEY CAN HAVE EITHER 'internal' OR 'external' SCOPE (internal IS 
THE DEFAULT) 
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•controlled' STORAGE CLASS 



ALLOCATION AND FREEING 



A 'controlled' VARIABLE IS ALLOCATED BY EXECUTION OF THE 'allocate' 
STATEMENT 



1 allocate id ; 

D alloc id1 , id2, ..., idN; 



A 'controlled' VARIABLE IS FREED BY THE EXECUTION OF THE 'free' 
STATEMENT 



Q free id ; 

Q free idl, id2 , ..., idN ; 
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'controlled' STORAGE CLASS 
STACKING 'controlled' VARIABLES 



• PL/I ALLOWS US TO ALLOCATE A 'controlled' VARIABLE MORE THAN ONCE 
BEFORE FREEING ITS STORAGE 



THE HISTORY OF ALLOCATIONS FOR EACH VARIABLE IS MAINTAINED ON A 
STACK SO THAT: 



II EACH 'allocate' STATEMENT LEAVES EARLIER ALLOCATIONS OF THAT 
VARIABLE UNDISTURBED 



fl A 'free' STATEMENT FREES THE MOST RECENTLY ALLOCATED SPACE 
FOR THAT VARIABLE 



EACH TIME THE VARIABLE IS REFERENCED, THE ONE "ON THE TOP OF 
THE STACK" IS ACCESSED (MOST RECENTLY ALLOCATED BUT NOT FREED) 



EXAMPLE 



P1: 


proc; 


del 


x float bin controlled; 




. . . (Computation #1) 




allocate x; 

x = 10; 

. . . (Computation #2) 




allocate x; 

x s 20; 

. . . (Computation #3) 




free x; 

... (Computation #4) 


end ; 


free x; 

. . . (Computation #5) 
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'controlled* STORAGE CLASS 



VARIABLE EXPRESSIONS IN ATTRIBUTES 



• WHEN A 'controlled' VARIABLE IS ALLOCATED, ANY EXTENT EXPRESSIONS 
AND INITIAL VALUE EXPRESSIONS ARE EVALUATED 



D EXTENTS ARE ARRAY BOUNDS, MAXIMUM STRING LENGTH, OR AREA SIZE 



D EXTENTS MUST BE SET BEFORE THE EXECUTION OF AN 'allocate' STATEMENT 



EXTENTS ARE SAVED IN A SYSTEM TEMPORARY 



D EXAMPLE 



P1 : proc; 

del n fixed bin init(O); 



n r 2; 

sllocstfi A* 

n = 0; ' /*HAS NO EFFECT ON EXTENT*/ 

put skip list (A); 

free A; 



Not To Be Reproduced 
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'controlled' STORAGE CLASS 
GUIDELINES FOR USING 'controlled' STORAGE 



'controlled' STORAGE IS GENERALLY MORE EXPENSIVE THAN THE BUILT-IN 
STORAGE MANAGEMENT MECHANISM OF AUTOMATIC OR STATIC STORAGE CLASSES 



• POSSIBLE APPLICATIONS: 



I WHEN A STACK OF VARIABLES IS NEEDED (THIS ALLOWS A PROGRAM WHICH 
USES STATIC VARIABLES TO BECOME REENTRANT BY REPLACING STATIC 
VARIABLES WITH 'controlled' VARIABLES) 



WHEN AN EXTERNAL VARIABLE MUST HAVE VARIABLE EXTENTS ('based' 
VARIABLES, WHICH COULD HAVE VARIABLE EXTENTS, CANNOT HAVE 'external' 
SCOPE) 



WHEN CONTROLLING THE AMOUNT OF STORAGE REQUIRED FOR A PROGRAM 
BECOMES CRITICAL 
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controlled' STORAGE CLASS 



GUIDELINES FOR USING 'controlled' STORAGE 



NOTE: PROGRAMS USING 'controlled' VARIABLES SHOULD PROVIDE AN 'on 
unit' FOR THE 'cleanup' CONDITION IN ORDER TO FREE ANY ALLOCATED 
STORAGE 



1 THE 'allocation' BUILTIN FUNCTION RETURNS (IN A fixed bin(17)) 
THE CURRENT ALLOCATION DEPTH OF STORAGE FOR A 'controlled' VARIABLE 



D EXAMPLE 



del cleanup condition; 
del x controlled; 

on cleanup begin; 

do i s 1 to allocation ( x) ; 

fi 
end; 
end; 
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defined' STORAGE CLASS 
CHARACTERISTICS 



A 'defined* VARIABLE IS USED TO ASSOCIATE A NEW NAME WITH AN EXISTING 
VARIABLE OR PART OF AN EXISTING VARIABLE — 



IT SUPPLIES A POTENTIALLY DIFFERENT INTERPRETATION (REDEFINITION) 
OF AN EXISTING GENERATION OF STORAGE 



fl IT MUST HAVE THE SAME DATA TYPE AS THE PART OF THE BASE VARIABLE 
BEING REDEFINED (EXAMPLE: A BIT STRING CANNOT BE 'defined' ON A 
CHARACTER STRING) 



fl IT ALWAYS HAS 'internal' SCOPE 



SINCE IT NEVER HAS STORAGE ALLOCATED FOR IT, A 'defined' VARIABLE 
CANNOT HAVE AN 'initial' ATTRIBUTE 



NOTE: USE OF 'defined' VARIABLES IS NOT THE SOLE MEANS OF 
"REDEFINITION" OF VARIABLES ('based' VARIABLES WILL BE DISCUSSED 
LATER) 
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'defined' STORAGE CLASS 



CHARACTERISTICS 



THE 'defined' ATTRIBUTE CONSISTS OF THE KEYWORD 'defined' FOLLOWED 
BY A REFERENCE TO A BASE VARIABLE 



• THERE ARE THREE WAYS TO USE 'defined' VARIABLES: 



i SIMPLE DEFINING 



I STRING OVERLAY DEFINING 



E 'isub' DEFINING 
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'defined' STORAGE CLASS 



SIMPLE DEFINING 



• EACH SCALER IN THE 'defined' VARIABLE AND THE CORRESPONDING SCALER 
IN THE BASE VARIABLE HAVE IDENTICAL STORAGE TYPES 



D EXAMPLE 1 



del array(5,5) char(4); 

del same_array(5,5) char(4) defined array; 

del vector_J(5) char(4) defined array; 

del vector~2(5) char(4) defined array(2,1); 



D EXAMPLE 2 



del 1 a, 

2 b(n) , 

3 c float bin, 

3 d float bin, 
2 e ehar(6); 

del x float defined( a.b(i-2) .d) ; 

del Y(n) float defined( a.b(») .d) ; 

del 1 z defined(a.b( j) ) , 
2 z1 float bin, 
2 z2 float bin; 



NOTE: THE BASE VARIABLE MAY MOT BE A 'defined' VARIABLE OR A NAMED 
CONSTANT 
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•defined' STORAGE CLASS 



STRING OVERLAY DEFINING 



• A STRING 'defined' VARIABLE IS MAPPED ONTO ALL OR PART OF THE STORAGE 
OF A STRING BASE VARIABLE 



II VALID FOR ALL STRING TYPES AS LONG AS THEY ARE 'nonvarying unaligned' 



MUST MATCH BITS ONTO BITS OR CHARACTERS ONTO CHARACTERS 



D PICTURED STRINGS CAN BE USED AS THE BASE VARIABLE, A FACT THAT 
PROVIDES 'defined' STORAGE ONE OF ITS MOST POWERFUL FACILITIES 



II EXAMPLE 



del a pic "999v.999es99"; 

del exponent char (3) defined (a) position (9); 



II THE 'position' OR 'pos» ATTRIBUTE CAN BE USED TO START THE 'defined' 
VARIABLE AT SOME BIT OR CHARACTER POSITION" OTHER THAN THE FIRST 
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•defined* STORAGE CLASS 



STRING OVERLAY DEFINING 



D EXAMPLES 



del 
del 
del 



del 
del 



A(5) char(2) unal; 
B char(8) def(A); 
1 C def(A), 

2 X char(5) unal , 

2 Y char(5) unal; 
D char(5) def(A) pos(6); 
E char(5) def(A(2)) pos(2); 



A 
B 
C 



A(1) 



m 



A(2) 



A{3) 



A(4) 



A{5) 



P^I | ! : ! : ! : ! A ! p!:!:a tm$$M KM$mi VUimmi 

HH Bsa»ga feaMssI lig»sal fesMi^ 



ex 



] 



][ 



C.Y 



•[ 
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•defined' STORAGE CLASS 



•isub* DEFINING 



A FACILITY OF PL/I WHICH ALLOWS A 'defined' ARRAY TO MAP ONTO A 
BASE ARRAY IN A SPECIALIZED MANNER 



II THE VALUE OF THE 'isub' REFERS TO THE SUBSCRIPT OF THE DEFINED 
ARRAY, NOT THE BASE ARRAY 



I EXAMPLE 



del A(3,4) float bin; 

del Q(3) float bin defined A(1sub,4); 

del TRANS(4,3) float bin defined( A(2sub , 1sub) ) ; 

Q(1) — > A(1,4) 

Q(2) — > A(2,4) 

Q(3) — > A(3,4) 



THE ARRAY 'Q' DEFINES THE FOURTH COLUMN OF 'A' 



Q THE ARRAY 'TRANS' REPRESENTS THE TRANSPOSE OF ARRAY *A T 

D IT REPRESENTS AN INTERPRETATION OF 'A' STORED IN COLUMN-MAJOR 
ORDER INSTEAD OF ROW-MAJOR ORDER 

D THIS CAN BE USEFUL FOR PASSING ARRAY ARGUMENTS FROM FORTRAN 
TO PL/I PROGRAMS AND VICE VERSA 
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•defined* STORAGE CLASS 



isub' DEFINING 



D CONSIDER A PL/1 2X2 ARRAY: 

AC1 ,1) = 1 A(1,2) = 2 

A(2,1) = 3 A(2,2) = 4 

I PL/1 WOULD STORE IT IN MEMORY IN ROW MAJOR ORDER 



1 


2 


3 


4 



D FORTRAN WOULD, HOWEVER, STORE IT IN COLUMN MAJOR ORDER 



T 

iRl 



13 2 4 



WHERE FORTRAN EXPECTS TO FIND A(2,1) 



Q PL/I MUST THEREFORE PASS FORTRAN A TRANSPOSE! 



del A(2,'2) fixed bin; 
del transpose A (2.2) fixed bin 
deTined A(2sub , 1sub) ; 



call fortran_prog ( transpose^ A) ; 
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•defined' STORAGE CLASS 



GUIDELINES FOR USING 'defined' STORAGE 



• 'defined' STORAGE MANAGEMENT IS "IN COMPETITION" WITH 'based' STORAGE 
MANAGEMENT 



'based' STORAGE MANAGEMENT IS MUCH MORE GENERAL 



D FOR MULTICS, 'based' IS GENERALLY PREFERRED OVER 'defined' STORAGE 
MANAGEMENT 



• USUALLY USED ONLY FOR THE ONE UNIQUE FEATURE PROVIDED — 'isub» 
DEFINING 



YOU ARE NOW READY FOR WORKSHOP 
#1 
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Topic III BASED STORAGE Topic III 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 



1. Allocate and free based variables in the same manner as 
controlled variables. 



2. Differentiate between packed and unpacked pointers, 



3. Use builtin functions to manipulate locator variables 
(pointers and offsets). 



4. Use based variables to redefine the interpretation of a 
particular area of storase. 



5. Use the "refer" option to implement self-defining data. 



6. Manipulate areas. 
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CHARACTERISTICS OF 'based' STORAGE 



ADVANCED AND POWERFUL STORAGE MANAGEMENT TECHNIQUE HAVING THREE MAJOR 
APPLICATIONS 



I EXPLICITLY ALLOCATING AND FREEING SPACE MUCH LIKE CONTROLLED STORAGE 



I EQUIVALENCING TO OR OVERLAYING A TEMPLATE UPON THE STORAGE GENERATED 
FOR SOME OTHER VARIABLE, MUCH LIKE DEFINED STORAGE 



I ACCESSING A SEGMENT IN THE VIRTUAL MEMORY DIRECTLY, THUS ENABLING 
I/O TO A SEGMENT WITHOUT USING I/O STATEMENTS 



• THE SCOPE OF A 'based' VARIABLE IS ALWAYS 'internal' 



a l»tir r\e» /*t h n **wtai 



inc. uc.v,i*Aiuiij.un ur a. ■ oasea ■ vakiabLE DESIGNATES ONLY THE DATA TYPE 
AND STORAGE TYPE ATTRIBUTE VALUES FOR THAT VARIABLE — 



II IT DOES NOT DESIGNATE THE LOCATION OF THE VARIABLE 



D HENCE, EVERY REFERENCE TO A 'based' VARIABLE MUST BE QUALIFIED 
WITH A LOCATOR VALUE 



I LOCATOR VALUES CAN BE 'pointer' OR 'offset' VALUES 
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THE 'based' ATTRIBUTE 



A 'based' VARIABLE IS DECLARED WITH THE KEYWORD 'based' OPTIONALLY 
FOLLOWED BY A PARENTHESIZED LOCATOR VARIABLE 



1 del x fixed bin based; 

II EVERY REFERENCE TO 'x' MUST BE QUALIFIED BY A LOCATOR VARIABLE 



D del x fixed bin based(p); 
del p pointer; 

I THE LOCATOR VARIABLE 'p» IS IMPLICITLY ASSOCIATED WITH ' x' 

EXPLICIT LOCATOR QUALIFICATION IS NOT NECESSARY (BUT IS 
RECOMMENDED) 



EVERY 'based' VARIABLE REFERENCE MUST BE QUALIFIED BY A LOCATOR 
VALUE, EITHER: 



D EXPLICITLY (USING THE -> OPERATOR) 



OR IMPLICITLY (IF THE VARIABLE WAS DECLARED WITH THE ' based (locref) ' 
ATTRIBUTE) 
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THE 'based' ATTRIBUTE 



EXAMPLE (EXPLICITLY QUALIFIED) 



del 
del 
del 


A dec(5,2) based 
p pointer; 
sysprint file;. 


in 


it(0); 


■ • ■ 

allocate A set(p) ; 






p->i 


• • • 

I = 5; 






put 


list (p->A); 






free 


• • • 

i p->A; 







fl EXAMPLE (IMPLICITLY QUALIFIED) 



del 


n fix 


ed 


bin; 






An! 

t* W .fe 






del 


beta 


pointer: 








• • • 










n = 


4; 










allocate 


s; 










• • » 










S = 


"abed 


ef 


> 






« • • 

free S; 
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EXPLICITLY ALLOCATED 'based* VARIABLES 



JUST AS IN THE CASE OF 'controlled' VARIABLES, BASED VARIABLES MAY 
BE EXPLICITLY ALLOCATED AND FREED 



I THE 'allocate' AND 'free' ARE USED 



t based' VARIABLES MAY BE ALLOCATED IN TWO DIFFERENT WAYS: 



E USING THE 'in ( area_name) ' OPTION 

I ALLOCATED IN THE 'area' SPECIFIED (ONLY 'based' VARIABLES MAY 
BE ALLOCATED IN AN 'area') 



Q OMITTING THIS OPTION 

1 ALLOCATED IN USER FREE AREA WITHIN [pd]>[ unique] .area .linker 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
THE 'allocate' AND 'free' STATEMENTS- 



• THE 'allocate' AND 'free' STATEMENTS HAVE THE FOLLOWING FORM WHEN 
USED FOR 'based' VARIABLES: 



E allocate _id [ set( locref )] [in( arearef )] ; 

1 WHERE 

I id IS THE NAME OF THE 'based' VARIABLE 

E set( locref ) IS USED TO DESIGNATE THE LOCATOR VARIABLE locref 
AS THE "ADDRESS" OF THE BEGINNING OF STORAGE GENERATED FOR 
THE 'based' VARIABLE id; 

MAY BE OMITTED IF THE VARIABLE id WAS DECLARED WITH THE 
* based ( locref) ' ATTRIBUTE 

D locref MUST SPECIFY A pointer OR offset 

in( arearef) SPECIFIES THE • area' IN WHICH id IS TO BE ALLOCATED 

1 MAY BE OMITTED 



11 free _id [in( arearef ) ] ; 

S WHERE 

I id IS THE 'based' VARIABLE TO BE FREED AND MIGHT HAVE TO 
BE PTR QUALIFIED 

J in( arearef ) IS USED IF THE VARIABLE id WAS ALLOCATED IN 
THE 'area' arearef (AND IS OTHERWISE OMITTED) 

D NOTE: POINTER IS NULLED AFTER 'based' VARIABLE IS FREED 
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EXAMPLE 



EXPLICITLY ALLOCATED 'based' VARIABLES 
.THE 'allocate' AND 'free' STATEMENTS 



P1 



proc; 



del a(5,2) fixed based; 

del c char(40) based(pl); 

del AREA area; /• INTERNAL AUTOMATIC, BY DEFAULT */ 

del (p1,p2) pointer; 

del sysprint file; 

allocate a set(p2); 
p2 -> a = 0; 
allocate c in(AREA); 
c = "abedefg"; 



put skip(2) data(p2 -> a); 
free p2 -> a, c in(AREA); 
end P1 ; 
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EXPLICITLY ALLOCATED 'based' VARIABLES 



area' DATA TYPES 



• THE PL/I DATA TYPE 'area' PROVIDES A POWERFUL FACILITY FOR STORAGE 
MANAGEMENT 



BENEFITS OF 'area' MANAGEMENT 



I OPTIONS LIKE ZERO_ON_FREEING, ZERO ON_ALLOCATING, AND 

EXTENSIBILITY 



I ENABLES THE USE OF PL/1 OFFSETS 



J EASY FREEING WITH 'empty' BUILTIN 



• AN 'area' VARIABLE IS USED BY THE PROGRAMMER AS A MANAGED "POOL" OF 
FREE STORAGE, TO HOLD 'based' VARIABLES 



• THE MAXIMUM SIZE OF A NON-EXTENSIBLE 'area' IS 256K WORDS 



I THE CAPACITY IS ALWAYS SOMEWHAT LESS THAN THIS 



1 THE "XCUPATION RECORD" WHICH RESIDES AT THE BEGINNING OF AN 
•area' CATALOGS THE USAGE OF SPACE IN THE 'area' 



"ALLOCATION RECORDS" PRECEDE EACH BLOCK OF ALLOCATED STORAGE 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
CREATING PL/I AREAS 



• AN 'area' MAY BE CREATED IN THREE WAYS: 



I BY THE 'declare' STATEMENT (del A area(area size);) 



area size; 

v/ v/\A/v>"CyVVJ 



area size SPECIFIES THE NUMBER OF WORDS TO BE ALLOCATED FOR 
THE "'"area' VARIABLE 'A' (THE DEFAULT IS 1024 WORDS) 



D THE LOCATION OF THE 'area' IS DETERMINED IN THE NORMAL FASHION, 
BY THE EVALUATION OF THE STORAGE CLASS ATTRIBUTE 

D POSSIBLE ATTRIBUTES ARE static, automatic, internal, 
external, controlled AND based 

D del A area; 

/« automatic - 'A' WOULD BE ALLOCATED ON THE STACK */ 

D del B area based ( get_system__free_area_() ) ; 
del get_system_free_area_ entry returns (ptr); 

/* 'B» WOULD BE ALLOCATED IN "SYSTEM FREE STORAGE" »/ 



BY THE «define_area_' SUBROUTINE 

I THE CALLER SPECIFIES THE LOCATION OF THE 'area' BY SUPPLYING 
A POINTER TO A SEGMENT IN WHICH THE 'area' IS TO BE ALLOCATED 

I call define^ area_ (info_ptr, code); 

I IF A NULL POINTER IS SUPPLIED, THE SYSTEM ACQUIRES A SEGMENT 
FOR THE 'area' FROM THE PROCESS DIRECTORY TEMP SEG POOL 



I MUST BE USED IF A BASED AREA IS OVERLAYED UPON ARBITRARY 
STORAGE 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
CREATING PL/I AREAS 



BY THE f create_area» COMMAND (AG92) 

Q THE COMMAND-LEVEL INTERFACE TO f def ine_area_ ! 

D AT COMMAND-LEVEL: create_area area_seg -extensible 
IN PROGRAM: del area__ seg$ external area; 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES 



LOCATORS SPECIFY THE "ADDRESS" OF AN OBJECT, AND ARE USED TO QUALIFY 
'based' VARIABLE REFERENCES 



TWO TYPES OF 'locator' VARIABLES: 

D 'pointer' 

Q CONTAINS THE ABSOLUTE ADDRESS OF A BIT IN THE VIRTUAL MEMORY 

I MAY BE ALIGNED OR UNALIGNED 

i AN ALIGNED POINTER (DEFAULT) 

IS DOUBLE WORD ALIGNED 

1 IS A PAIR OF WORDS CONTAINING: 
15-BIT SEGMENT NUMBER 

3-BIT RING NUMBER 

6-BIT TAG FIELD CONTAINING OCTAL 43 

18-BIT WORD OFFSET 

6-BIT BIT OFFSET 

11 IS DECLARED 

del my__pointer pointer; 

1 IS SOMETIMES REFERRED TO AS AN ITS (INDIRECT TO SEGMENT) 
PAIR 



Not To Be Reproduced 3-10 F15C 



EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES 

AN UNALIGNED POINTER 
I IS BIT ALIGNED 
D IS A SINGLE WORD CONTAINING 

6-BIT BIT OFFSET 

12-BIT SEGMENT NUMBER 

18-BIT WORD OFFSET 
I IS DECLARED 

del my_po inter unal ptr; 
I IS SOMETIMES REFERRED TO AS A PACKED POINTER 
1 IS HANDLED BY SPECIAL HARDWARE INSTRUCTIONS 



SINCE ONE OF THE COMPONENTS OF A 'pointer' IS THE SEGMENT 
NUMBER, THE 'pointer' VALUE IS INVALID ACROSS PROCESS BOUNDARIES 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES 



D 'offset' 

AN ADDRESS TO A BIT IN AN 'area 1 , RELATIVE TO THE BASE OF 
THAT 'area' 

Q COMPOSED OF A 18 BIT WORD OFFSET AND A 6-BIT BIT OFFSET 

1 AN 'offset' DECLARATION MUST BE QUALIFIED BY THE NAME OF THE 
'area' INTO WHICH THE 'oTFset' REFERS IF IT IS TO BE USED IN 
A 'based' VARIABLE REFERENCE 

D AN 'offset' IS VALID ACROSS PROCESS BOUNDARIES, SINCE IT DOES 
MOT REFER! TO A SEGMENT NUMBER 

I THE PL/I 'offset' ATTRIBUTE IS USED TO DECLARE AN 'offset' 
VARIABLE 

5 del offl offset; 

I del off2 offset(A); WHERE 'A' HAS BEEN DECLARED AN 'area' 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES 



EXAMPLE USING POINTERS AND OFFSETS 



based_prog : proo; 


del 


sysprint file; 


del 


A area; /* DEFAULT SIZE IS 1024 WORDS */ 


del 


x fixed bin based; 


del 


c char (8) based; 


del 


P Ptr; 


del 


o offset(A); 




allocate x set ( o) in (A); 




o -> x = 15; 




allocate c set ( p) ; 




p -> c = "abedefgh"; 




put skip data (o -> x, p -> e); 




free o -> x in (A); 




free p -> c; 


end 


based_prog; 



I RESULT OF RUNNING ABOVE EXAMPLE 
! based_prog 

x= 15 o= h abedefgh"; 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR 'builtin' FUNCTIONS 



• PL/I BUILTIN FUNCTIONS (AM83) ARE PROVIDED TO CONVERT BETWEEN 'pointer' 
AND 'offset' LOCATOR DATA TYPES: 



B THE 'pointer' BUILTIN FUNCTION 

H CONVERTS AN 'offset' IN AN 'area* INTO A 'pointer* 

pointer(X,A) 
ptr(X,A) 

RETURNS A POINTER POINTING TO 'offset' 'X' IN 'area' 'A' 



D THE 'offset' BUILTIN FUNCTION 

I CONVERTS A 'pointer' WHICH POINTS TO A LOCATION IN AN 'area' 
INTO THE 'offset 1 OF THAT LOCATION IN THE 'area' 

Q offset(P,A) 

RETURNS AN 'offset' TO THE 'based' VARIABLE LOCATED BY 
•pointer' *P* IN 'area' 'A' 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR •builtin* FUNCTIONS 



• ADDITIONAL BUILTIN FUNCTIONS FOR THE MANIPULATION OF 'locator' AND 
'area' VARIABLES: 



1 THE 'null' BUILTIN FUNCTION 



H RETURNS THE VALUE OF THE NULL POINTER, THAT IS, A POINTER TO 
SEGMENT NUMBER -1 WITH WORD OFFSET 1 



I IS USED TO TEST THE VALIDITY OF 'pointer' VALUES OR TO INITIALIZE 
THEM 



I NOTE THAT A 'pointer' VARIABLE CAN BE IN ONE OF THREE STATES: 

I UNDEFINED - NO VALUE HAS BEEN ASSIGNED, AND IF USED, 
»fault_tag_1 ' CONDITION IS USUALLY SIGNALLED 

1 NULL - THE 'null' BUILTIN HAS BEEN USED TO INITIALIZE THE 
•pointer' - AN ATTEMPT TO USE SUCH A 'pointer' USUALLY 
RESULTS IN THE SIGNALLING OF THE 'null^ pointer' CONDITION 

1 NON-NULL - A LEGITIMATE ADDRESS HAS BEEN ASSIGNED 



S THE 'nullo' BUILTIN FUNCTION 

II IS USED TO TEST THE VALIDITY OF 'offset' VALUES AND TO INITIALIZE 
THEM 

I A NULL OFFSET IS ALL "ONES" 



Not To Be Reproduced 3-15 F15C 



EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR 'builtin' FUNCTIONS 

Q THE 'addr' BUILTIN FUNCTION 

1 RETURNS THE ADDRESS' OF ITS ARGUMENT AS A 'pointer' VALUE 

I addr(x) RETURNS A 'pointer' WHICH LOCATES THE GENERATION OF 
STORAGE FOR 'x' 

D THE ^empty ' BUILTIN FUNCTION 

D RETURNS THE "EMPTY" OR "NULL" VALUE OF DATA TYPE 'area' 

D IS USED TO DETERMINE IF AN 'area' IS EMPTY AND IS ALSO USED 
TO INITIALIZE AN 'area' 

Q A "QUICK AND DIRTY" FREEING MECHANISM 

J THE NONSTANDARD 'pointer' BUfLTIN FUNCTION 

I RETURNS A 'pointer' VALUE GIVEN A 'pointer' POINTING ANYWHERE 
IN A SEGMENT AND A WORD OFFSET EXPRESSED AS AN ARITHMETIC OR 
BIT STRING VALUE 

fl pointer(P.N) OR ptr(P,N) RETURNS A 'pointer' TO THE Nth WORD 
OF THE SEGMENT 

1 IS DISTINGUISHED FROM THE STANDARD 'pointer' BUILTIN FUNCTION 
BY THE DATA TYPE OF THE ARGUMENTS 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR 'builtin' FUNCTIONS 

THE NONSTANDARD 'addrel' BUILTIN FUNCTION 

RETURNS A 'pointer' TO A WORD RELATIVE TO ANOTHER POINTER 

1 addrel (P,N) POINTS TO A WORD N WORDS AWAY FROM P 

I THE RESULTING POINTER HAS A BIT OFFSET, REGARDLESS OF 
P'S BIT OFFSET 

1 N IS AS IN THE ABOVE NONSTANDARD pointer BUILTIN 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
USING EXPLICITLY ALLOCATED 'based' STORAGE 



• EXPLICITLY ALLOCATED 'based' STORAGE IS GENERALLY USED FOR ONE OF 
THREE PURPOSES: 



I TO DIRECTLY CONTROL THE ALLOCATION AND FREEING OF STORAGE 



B TO PROVIDE STORAGE FOR DATA ITEMS WHOSE EXTENTS ARE NOT KNOWN AT 
COMPILE TIME 



1 TO TAKE ADVANTAGE OF CERTAIN FEATURES MADE AVAILABLE THROUGH THE 
USE OF 'area 1 VARIABLES 

I ZERO ON ALLOCATION 

1 ZERO ON FREEING 

I MASS FREEING OF ALLOCATED VARIABLES 

B EXTENSIBILITY OF AREAS 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
USING EXPLICITLY ALLOCATED 'based' STORAGE 



• EXPLICITLY ALLOCATED 'based' VARIABLES CAN BE USED TO PROVIDE STORAGE 
FOR DATA ITEMS WHOSE EXTENTS ARE NOT KNOWN AT COMPILE TIME 



I ADJUSTABLE EXTENTS ARE ARRAY BOUNDS, MAXIMUM STRING LENGTHS, AND 
•area' SIZES 



I UNLIKE 'controlled' VARIABLES, FOR 'based' VARIABLES, THE VALUES 
OF VARIABLE EXTENTS ARE COMPUTED FOR EACH REFERENCE 

THAT IS, THE ADJUSTED EXTENTS ARE NOT SAVED WHEN THE VARIABLE 
IS FIRST ALLOCATED 

1 IT IS THE RESPONSIBILITY OF THE PROGRAM TO PRESERVE SUCH EXTENTS 
TO AVOID VIOLATING THE PL/I CONSISTENCY RULES 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
USING EXPLICITLY ALLOCATED 'based' STORAGE 



EXAMPLE OF AN INVALID PROGRAM 



P1 : proc; 

del n fixed bin; 

del S char(n+2) based(beta); 

del beta pointer; 



n s 4; 
allocate 


S; 


i • • • 

~7n's 100; 
S = "abed 


ef"; 


• • • 

free S; 
end; 





D THIS PROGRAM IS INVALID 

I WHEN THE 'based' VARIABLE 'S' IS ALLOCATED, IT IS GIVEN 6 
BYTES OF STORAGE 

I WHEN IT IS REFERENCED IN THE ASSIGNMENT STATEMENT, THE 
EXTENTS ARE RECOMPUTED TO 102, AND THE STRING "abedef" 
WILL BE PADDED TO A LENGTH OF 102 BEFORE BEING ASSIGNED 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
THE 'refer' OPTION 



SINCE THE VARIABLE EXTENTS OF 'based' VARIABLES ARE NOT SAVED BY 
PL/I, A SPECIAL FEATURE, THE 'refer' OPTION IS PROVIDED 



I IT IS USED TO SAVE THE VALUE CALCULATED FOR VARIABLE EXTENTS OF 
A 'based' VARIABLE WHEN IT IS ALLOCATED 



I IT IS USED WITHIN A STRUCTURE VARIABLE TO CREATE A "SELF-DEFINING 
STRUCTURE", WHICH CARRIES ITS OWN EXTENTS 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
THE 'refer' OPTION 



B A VALID EXAMPLE 



P3: 


proc; 


del 
del 

del 


n fixed bin; 

1 Spair based(beta) , 

2 n2 fixed bin, 

2 S char(n+2 refer(n2)); 
beta ptr ; 




• • • 

n = 4; 
allocate Spair; 




n = 100; 

Spair. S = "abedef; 


end 


• a • 

free Spair; 
P3; 



NOTE: A PARENTHESIZED REFERENCE FOLLOWING THE KEYWORD 'refer' 
MUST DESIGNATE A SCALAR MEMBER DEFINED EARLIER IN THE SAME STRUCTURE 



I AT ALLOCATION TIME, ANY INITIAL EXTENT EXPRESSION IS EVALUATED, 
AND IS .SAVED IN THE MEMBER REFERENCED BY THE 'refer' OPTION 
CLAUSE "~ ~~ 



I ON SUBSEQUENT REFERENCES TO THE 'based' ADJUSTABLE VARIABLE, THE 
EXTENT IS DETERMINED BY REFERRING TO THE MEMBER 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
USING • area' VARIABLES 



EXPLICITLY ALLOCATED 'based' VARIABLES MAY BE USED TO TAKE ADVANTAGE 
OF THE STORAGE MANAGEMENT FACILITIES OFFERED BY THE- PL/I 'area' 
VARIABLES 



• 



NOTE THAT THE ONLY TYPE OF VARIABLE WHICH MAY BE ALLOCATED IN AN 
'area' IS AN EXPLICITLY ALLOCATED 'based' VARIABLE 



NOTE ALSO THAT PL/1 'offset' VALUES CAN ONLY LOCATE STORAGE WITHIN 
AREAS 
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EQUIVALENCED 'based' STORAGE 



• THE USE OF EQUIVALENCED 'based' VARIABLES IS ONE OF THE MOST POWERFUL 
STORAGE MANAGEMENT CAPABILITIES OFFERED BY PL/I 



UNLIKE EXPLICITLY ALLOCATED 'based' VARIABLES, AN EQUIVALENCED 'based' 
VARIABLE: 



11 IS SUPERIMPOSED ON OR EQUIVALENCED TO A PREVIOUSLY ALLOCATED 
"BASE" VARIABLE 



I NEVER HAS STORAGE OF ITS OWN, AND THUS IS NEVER ALLOCATED OR 
FREED 



• THE LOCATOR VALUE USED TO REFERENCE THE BASE VARIABLE IS OBTAINED 
BY THE 'addr' BUILTIN FUNCTION 



EXAMPLE 



del a fixed bin (35); 

del b fixed bin (35) based (addr(a)); 

a = 5; 
b = 2; 
put skip list ( a,b) ; 
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EQUIVALENCED 'based* STORAGE 



• ADDITIONAL EXAMPLES (NOTE: FOR THESE EXAMPLES, THE DATA TYPE OF 
THE 'based' VARIABLE IS THE SAME AS THAT OF THE BASE VARIABLE) 



Q EXAMPLE 1 



1 EXAMPLE 2 



PI: 


proc; 


del 
del 


x fixed dec(5,2); 

y fixed dec(5,2) based; 


del 
del 


p ptr ; 
(sysin ,sysprint) file; 


end 


p = addr( x) ; 
get list(x) ; 

put skip list(2 * p->y); 
PI; 





m • * 


del 


1 A(5), 




2 x fixed bin, 




2 y char(6); 


del 


1 B based , 




2 r fixed bin, 




2 s char(6); 


del 


P Ptr; 




p = addr(A(3)); 




p -> B.s = "third"; 


/* 


SETS A(3).y TO "third" */ 



Not To Be Reproduced 



3-25 



F15C 



EQUIVALENCED 'based' STORAGE 



* IT IS ALSO POSSIBLE FOR THE DATA TYPES OF THE 'based' AND BASE 
VARIABLE TO DIFFER 



I EXAMPLE 1 



del x fixed bin(35); 

del y bitC 36) based (addr(x)); 

x = 5; 

put skip list (x,y); 



I EXAMPLE 2 



del number(1024) float bin; 

del 1 f loat_num based , 

2 sign bit( 1 ) unal , 
2 exponent bit(7) unal, 
2 m_sign bit(1) unal, 
2 mantissa bit(27) unal; 

• • • 

p = addr( number(43)) ; 



1 p -> float_num MEANS number(43) 

p -> sign MEANS bit of number(43) 

Q p -> mantissa MEANS bits 9-35 of number(43) 
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EQUIVALENCED 'based' STORAGE 



del x char(8) varying initC'ABC"); 

del 1 y based (addr(x)), 

2 length fixed bin (35), 

2 actual_string char (8); 



B 




length 



actual_string 



x = "BONJOUR"; 

if yJength*? 

then put list (y.actual_string); 
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AN APPLICATION FOR 'based' VARIABLES 
LINKED INFORMATION STRUCTURES 



• EQUIVALENCED 'based' STRUCTURES CAN BE USED TO PROVIDE STORAGE FOR 
DATA ITEMS WHICH HAVE BEEN ORGANIZED INTO AN ARBITRARILY LINKED 
INFORMATION NETWORK 



J SINGLY AND DOUBLY LINKED LISTS 
I TERMINATING LISTS 
I CIRCULAR LISTS 

D TREES AND OTHER DIRECTED GRAPHS 

D OTHER INFORMATION NETWORKS 



• IT SHOULD BE NOTED THAT SUCH STRUCTURES ARE HEAVILY USED IN THE 
SUPERVISOR, AND THAT MOST OF THE SUPERVISOR DATABASES ARE 'based' 
STRUCTURES DEFINED IN "INCLUDE FILES" SUBORDINATE TO >ldd> include 
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AN APPLICATION FOR 'based* VARIABLES 
LINKED INFORMATION STRUCTURES ■ 



* AN EXAMPLE (from stack_frame.incl.pl1) 



aligned , 
: 7) ptr, 
points to 
points to 



ptr 



dcl 1 stack_frame based(sp) 
2 pointer_registers(0 
2 prev_sp pointer, /* 
2 next__sp pointer, /* 
2 return_ptr pointer, 
2 entry_Jptr pointer, 
2 opera"Eor_and__lp_ptr 
2 arg_ptr pointer, 
2 static_ptr ptr unaligned, 
2 support_ptr ptr unaligned, 
2 on__unit_relp1 bitd8) unaligned 
2 on""unit_relp2 bit(l8) unaligned 
2 translator__id bit(l8) unaligned 
2 operator return_offset bit(18) 
2 x(0: 7) bitd8) unaligned, 
2 a bit(36) , 
2 q bit(36), 
2 e bit(36) , 

2 timer bitC27) unaligned, 
2 pad bit(6) unaligned, 
2 ring__alarm__reg bit(3) unaligned; 



previous stack frame */ 
next stack frame */ 



unaligned 



• THERE ARE OVER 2000 SUCH 
DEMONSTRATES THEIR USAGE) 



INCLUDE FILES IN >ldd> include (TOPIC 5 



YOU ARE NOW READY FOR WORKSHOP 
#2 



Not To Be Reproduced 



3-29 
(End Of Topic) 



F15C 



TOPIC IV 
Introduction to Multics Subroutines 



Page 

What are System Subroutines? 4-1 

System Subroutine Conventions 4-2 

Using System Subroutines 4-3 

Status Codes 4-4 



4-i F15C 



Topic IV INTRODUCTION TO MULTICS SUBROUTINES Topic IV 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 

1. Give reasons for havins a set of Multics subroutines. 

2. Give seneral suidelines for use of Multics system 
subroutines. 

3. List some of the conventions followed when usins Multics 
system subroutines. 
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WHAT ARE SYSTEM SUBROUTINES? 



• SYSTEM SUBROUTINES ARE CALLABLE PROCEDURES USED BY THE MULTICS 
OPERATING SYSTEM 



I THEY ARE THE SUBROUTINES THAT THE PROGRAMMER USES TO PERFORM 
COMMAND LEVEL LIKE FUNCTIONS 



I THEY ARE THE PROCEDURES ACTUALLY CALLED BY COMMAND PROCEDURES 
(EXAMPLE: THE delete COMMAND PROCEDURE CALLS THE delete 
SUBROUTINE) 

« 

SOME SUBROUTINES HAVE A ONE-TO-ONE RELATION WITH MULTICS COMMANDS 
(EXAMPLE: send message_ SUBROUTINE PERFORMS THE send_message 
COMMAND FUNCTION FROM WITHIN A PROGRAM) 

OTHER SUBROUTINES PERFORM ONLY A SMALL PART OF WHAT AN ENTIRE 
COMMAND DOES. EXAMPLES: 

D iox_ SUBROUTINES ARE USED BY SEVERAL COMMANDS 

1 convert_date to_binary IS JUST ONE OF MANY SUBROUTINES 
CALLED BY THE enter_ab"i_request AND memo COMMANDS- 
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SYSTEM SUBROUTINE CONVENTIONS 



• SYSTEM SUBROUTINE ENTRY NAMES END IN AN UNDERSCORE ( ) 



• MANY SUBROUTINES HAVE SEVERAL ENTRY POINTS 

E hcs_$list_acl 
hcs_$make_seg 
hcs $ status 



• THEY ARE DOCUMENTED IN MULTICS SUBROUTINES & I/O MODULES (AG93) 



• THEY ARE LOCATED PRIMARILY IN >system_library_standard AND 
>system_library_1 



• THEY ARE WRITTEN IN PL/I OR ALM 
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USING SYSTEM SUBROUTINES 



• SINCE THEY ARE EXTERNAL SUBROUTINES, EACH MUST BE DECLARED IN THE 
USER'S PROGRAM AS 'external entry' 



THE DATA TYPES FOR THE PARAMETER LIST CAN BE FOUND IN THE MANUAL 
DESCRIPTION OF THE SUBROUTINE 



IF THEY ACCEPT A VARIABLE NUMBER OF ARGUMENTS, THEY ARE DECLARED 
'entry options (variable)' 



# SEVERAL MAKE USE OF STRUCTURES TO PASS DATA TO AND FROM THE CALLING 
PROCEDURE 



I IN THIS CASE, ONE OF THE ARGUMENTS PASSED TO THE PROCEDURE IS A 
POINTER TO THAT STRUCTURE 



I THE DECLARATIONS REQUIRED FOR THESE STRUCTURES ARE FOUND IN THE 
DOCUMENTATION FOR THE SUBROUTINE 



I THE DECLARATIONS OF SOME OF THESE STRUCTURES ARE FOUND IN INCLUDE 
FILES IN >ldd> include 



Q EXAMPLE: hcs_$status_ 

Q THIS SUBROUTINE IS PASSED A- POINTER TO A STRUCTURE INTO WHICH 
IT IS TO PUT ITS INFORMATION 

1 A DECLARATION FOR THAT STRUCTURE IS FOUND IN 

>ldd>include>status_structures.incl.pl1 (FURTHER DISCUSSED IN 
TOPIC 10) 
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STATUS CODES 



• ONE OF THE OUTPUT ARGUMENTS OF A SUBROUTINE IS USUALLY A 'status 
code' 



THE 'status code' IS THE MEANS BY WHICH THE CALLED PROCEDURE HAY 
REPORT ANY UNUSUAL OCCURRENCE TO ITS IMMEDIATE CALLER 



THE VARIABLE THAT RECEIVES THE 'status code' MUST BE DECLARED 
•fixed bin(35)' 



IF THE SUBROUTINE RUNS TO COMPLETION WITH ABSOLUTELY NO ABNORMAL 
CONDITIONS TO REPORT, THE STATUS CODE IS (ZERO) 



• com_err_ 

USED TO REPORT ERRORS FROM WITHIN A PROGRAM 

1 TYPICAL USAGE 

del com_err entry options (variable); 
del code fixed bin(35); 

• • • 

call hes $status_*( .code); 

if code "*= ~" 
then do; 

call com_err_ ( code , n gamma !! ); 

return; ~~ ~~ -* 
end; 

I IF AN ERROR OCCURRED, IT MIGHT PRINT SOMETHING LIKE: 
gamma: Incorrect access to directory containing... 

Q SOME NON-ZERO STATUS CODES DO NOT INDICATE AN ERROR 
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STATUS CODES 



D STATUS CODES AND THEIR MEANINGS ARE LISTED IN CHAPTER 7 OF THE 
MULTICS PROGRAMMER'S REFERENCE GUIDE (AG91 ) 



i THE STANDARD STATUS CODES AND THEIR CORRESPONDING MESSAGES ARE 
IN A SEGMENT CALLED error_table_, WHICH IS IN >s!1 



I IT IS POSSIBLE TO TEST FOR A PARTICULAR STATUS CODE VALUE USING 
THE SYMBOLIC REPRESENTATION 

del error_table_$segknown external fixed bin(35); 

• • • 

if code = error_tab!e_$seg known 
then do; 

call com__err (code, "beta"); 
goto try~agaTn; 
end; 
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STATUS CODES 



THE probe 'display' REQUEST CAN BE USED TO DISPLAY THE ERROR 
MESSAGE ASSOCIATED WITH A STATUS CODE 



segknown: proc; 

del initiate__file_ 

del seg_ptr 

del bit_count 

del code 

del null 



entry (char(»), char(») , bit(*), ptr , 
fixed bin(24), fixed bin(35)); 
pointer; 
fixed bin (24); 
fixed bin (35); 
builtin; 



call initiate_file_ (••>udd>MED>jcj>15c" , "foo", "101 "b, seg_ptr, 
"" ~" bit_count, code); ~" 

end /* segknown */; 



r 11:41 0.100 3 

! segknown 

Stopped after line 10 of segknown. (level 5) 
! sc 

call initiate_file_ (">udd>MED>jcj>15c" , "foo", "1 01 "b , seg_ptr 
"" "~ bit_count. code); 

v seg_ptr 

seg_ptr = null 

v code 

code = 8589679427 

display code code 

error_table_$noentry "Entry not found." 

q 

r 11:42 0.733 86 

! Is foo 
list: foo not found 
r 11:42 0.212 11 
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Topic V ADVANCED BASED VARIABLE USAGE Topic V 

OBJECTIVES! 

Upon completion of this topic* students should be able to: 



1. Use Multics subroutines to manipulate sesments directly 
instead of usins PL/1 I/O statements. 



2. Manipulate archive components usins Multics subroutines. 



3. Examine some system databases usins based structures and 
Multics subroutines. 
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GAINING DIRECT ACCESS TO SEGMENTS 



MOTIVATION 



• EQUIVALENCED BASED VARIABLES CAN BE USED TO GAIN DIRECT ACCESS TO 
SEGMENTS IN THE VIRTUAL MEMORY 



I IN THIS WAY, AN ENTIRE DATA SEGMENT CAN BE ACCESSED WITHOUT 
RESORTING TO LANGUAGE I/O 



I ONE MUST OBTAIN A 'pointer' TO THE SEGMENT IN ORDER TO GAIN 
DIRECT ACCESS TO IT 



I THE FOLLOWING PAGES SHOW SUBROUTINES THAT RETURN A POINTER TO A 
SEGMENT 
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GAINING DIRECT ACCESS TO SEGMENTS 
OBTAINING A POINTER TO A SEGMENT 

• MULTICS SUBROUTINES WHICH OBTAIN A 'pointer' TO A SEGMENT: 

I he s__$ make_seg 

D BASIC FUNCTIONS 

I SEGMENT CREATION IF IT DOES NOT EXIST 
1 SEGMENT INITIATION 

I USAGE 



del hes $make seg entry 
(chart*)," 
char(*) , 
char(*) , 
fixed bin(5), 
ptr , 
fixed bin(35)); 



call hcs_$make_seg 
( dir_name7 
entryname, 
ref_name, 
mod e , 
seg_ptr , 
code) ; 



/* INPUT */ 
/* INPUT */ 
/* INPUT */ 
/* INPUT */ 
/* OUTPUT */ 
/* OUTPUT */ 



/* PATH OF CONTAINING DIR'*/ 

/* SEGMENT NAME */ uW 

/* DESIRED REFERENCE NAME */ = 

/* ACCESS FOR THIS USER */ 

/* POINTS TO CREATED/FOUND SEG •/ 

/• STATUS CODE */ 
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GAINING DIRECT ACCESS TO SEGMENTS 
OBTAINING A POINTER TO A SEGMENT 



NOTES 



I IF SEGMENT DOESN'T EXIST, APPEND PERMISSION REQUIRED ON 
CONTAINING DIRECTORY 

H MAKING-KNOWN REQUIRES NONNULL ACCESS ON SEGMENT 

I IF entryname IS NULL, UNIQUE SEGNAME IS GENERATED 

I IF dir_name IS NULL, SEGMENT IS CREATED IN PROCESS DIRECTORY 

I ref_name USUALLY NULL 

I mode ENCODES THUSLY 

READ -> 01000b 

EXECUTE -> 00100b 
WRITE -> 00010b 

seg_ptr IS RETURNED NULL IF REAL TROUBLE WAS ENCOUNTERED 

1 code MIGHT BE NON-ZERO UNDER 'NORMAL' CIRCUMSTANCES: 

error_table_$ named up 
error~table~$segknown 
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GAINING DIRECT ACCESS TO SEGMENTS 
OBTAINING A POINTER TO A SEGMENT 



IF THE PROGRAMMER DOESN'T CARE IF THE SEGMENT ALREADY EXISTS 
OR IS ALREADY INITIATED HE RELIES ONLY ON THE MOM-NULL seg_ptr 



del hes $make__seg entry (char (*) , ohar (*), char (*), 
~" "~ fixed bin (5), ptr , fixed bin (35)); 

del com_err_ entry options (variable); 



call hcs_$make_ seg( seg_ptr, code); 

if seg__ptr = null() 
then do ; 

call com__err_ (code, "alpha"); 

• • • ' 

end; 



IF THE PROGRAMMER EXPECTS" TO BE CREATING A NEW SEGMENT AND 
DOES NOT WANT TO REFERENCE AN ALREADY EXISTING SEGMENT, HE 
MUST CHECK THE CODE' 



del hes $make_seg entry (char (*), char (*), char (*), 
~ fixed bin (5), ptr, fixed bin (35)); 

del com__ err_ entry options (variable); 
del error_table_$ named up fixed bin(35) ext static; 
del error~table~$segknown fixed bin(35) ext static; 



call hes $make_seg ( seg_ptr , code); 

if seg_p'£r = riullO S code = error_tabie_$seg known 

I code = error~table~$ named up 
then do; "" "" 

call cora — err__ (code, "alpha"); 

• • • 

end; 
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GAINING DIRECT ACCESS TO SEGMENTS 
OBTAINING A POINTER TO A SEGMENT 



Q initiate_file_ 

Q BASIC FUNCTIONS 

I MAKES A SEGMENT KNOWN WITH A NULL REFERENCE NAME 

1 CHECKS THAT THE USER'S PROCESS HAS AT LEAST THE DESIRED 
ACCESS ON THE SEGMENT 

I RETURNS A POINTER TO THE SEGMENT 

1 RETURNS A BIT COUNT 



I USAGE 



del initiate file entry 

(char(*)7 
char(*) , 
bit(») , 
pointer , 

fixed binary (24) , 
fixed binary (35)); 



call initiate_file_ 
(dirname, 
entryname , 
mod e , 
seg__ptr , 
bit~count , 
code) ; 



/* INPUT »/ 
/* INPUT */ 
/* INPUT */ 
/* OUTPUT */ 
/* OUTPUT */ 
/* OUTPUT */ 



/* PATH OF CONTAINING DIR */ 
/* SEGMENT NAME */ 
/* REQUIRED ACCESS MODE */ 
/* POINTS TO INITIATED SEG */ 
/* BIT COUNT OF SEGMENT */ 
/* STANDARD SYSTEM CODE */ 
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GAINING DIRECT ACCESS TO SEGMENTS 
OBTAINING A POINTER TO A SEGMENT 



NOTES 

I THE SEGMENT MUST EXIST 

I MAKING-KNOWN REQUIRES NONNULL ACCESS ON THE SEGMENT, AS 
WELL AS THE REQUIRED MODES SPECIFIED IN THE CALL 

1 mode ENCODES THUSLY 

READ -> "100"b 

EXECUTE -> w 010"b 
WRITE -> "001 "b 

(>ldd>include> access mode_values.incl .pl1 CONTAINS NAMED 
CONSTANTS FOR THESE ICCESS MODES) 

D seg_ptr IS NULL IF THE SEGMENT IS NOT MADE KNOWN 

I code IS A STANDARD STATUS CODE AND COULD BE: 

error_table_$no_r_ permission 
error~table_$no~e~permission 
error_table_$no_wTpermission 
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GAINING DIRECT ACCESS TO SEGMENTS 
OBTAINING A POINTER TO A SEGMENT 



D initiate_file_$ component 

BASIC FUNCTIONS 

II MAKES EITHER A SEGMENT OR AN ARCHIVE COMPONENT KNOWN WITH 
A NULL REFERENCE NAME 

I IF NO COMPONENT NAME IS SPECIFIED, THIS ENTRY POINT IS 
IDENTICAL TO initiate_file_ 

D USAGE 

del initiate file $component entry 

(char (*7, /* INPUT */ 

char (*) , /* INPUT */ 

char (*) , /* INPUT */ 

bit (*) , /* INPUT */ 

pointer, /* OUTPUT */ 

fixed binary (24), /* OUTPUT */ 

fixed binary (35)); /* OUTPUT */ 

call initiate_file_$component 

(dirname, /* PATH OF CONTAINING DIR *L 

entryname, /* NAME OF SEGMENT OR ARCHIVE */ 

onuimnant nama /* MUTT f\D MAMff AF PrMDAMUirT */ 

*» **h* jj\* »««««« v »«M«u w , i 1« WU4* vn nniib w \y wit i vilbtll ' t 

mode, /* REQUIRED ACCESS MODE */ 

component ptr , /* PTR TO SEGMENT OR COMPONENT */ 

bit countT /* BIT COUNT OF SEGMENT OR COMPONENT */ 

code) ; /* STANDARD SYSTEM CODE »/ 



NOTES 



THE ARCHIVE COMPONENT MAY NOT BE MODIFIED (ONLY READ ACCESS 
IS PERMITTED) 

ONLY THE DATA STARTING AT THE POINTER AND EXTENDING AS FAR 
AS THE BIT COUNT MAY BE REFERENCED (NO DATA BEFORE OR 
AFTER THE COMPONENT MAY BE REFERENCED) 
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GAINING DIRECT ACCESS TO SEGMENTS 
OBTAINING A POINTER TO A SEGMENT 

Q TO OBTAIN A POINTER TO A COMPONENT WITHIN AN ARCHIVE SEGMENT SEE 
1 archive_$get_ component 
Q archive__$next_component 



• NOTE THAT THE SUBROUTINES DISCUSSED REQUIRE AN ABSOLUTE DIRECTORY 
PATHNAME 



• THE expand pathname SUBROUTINE CAN BE USED TO CONVERT A PATHNAME 
(WHETHER RELATIVE OR" ABSOLUTE) INTO THE REQUIRED DIRECTORY PATHNAME 
AND ENTRYNAME STRINGS 



II USAGE 

del expand pathname entry 

(charC*), charC) , char(»), fixed bin(35)); 

call expand pathname 

(rel path, 7* RELATIVE OR ABSOLUTE PATHNAME 

TO BE EXPANDED */ 

dir name, /« RETURNED DIRECTORY PORTION OF 

PATHNAME »/ 

entryname, /* RETURNED ENTRYNAME PORTION OF 

PATHNAME */ 
cod e) ; 
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GAINING DIRECT ACCESS TO SEGMENTS 
AN EXAMPLE 



stack_tracer : proc; 

Jinclude staek_header ; 
Jinclude stackTframe; 

del com__err_ entry options (variable); 

del get~pdir entry () returns (char (168)); 

del initiate" file entry (char (*), char (*) , bit (*), pointer, 
~* " fixed binary (24), fixed binary (35)); 

del interpret_ptr__ entry ( ptr , ptr, ptr) ; 

del bit_count fixed binary (24); 

del code fixed bin (35); 

del ME char (12) static 

init ("stack^tracer") options (constant); 

del no_ frames fixed bin; 
del 1 owner , 

2 message char (64), 

2 segname char (32), 

2 entryname char (33); 
del ( save__ptr ,5^) 

shp)"" ptr; 

del sysprint file; 
del ( addr , 
ltrim, 

null) builtin; 

/* GET POINTER TO BASE OF STACK SEGMENT */ 

call initiate_file_ (get_pdir_ () , "stack 4", "100"b, 

~" "" shp, bit_count, codeT; 
if shp = null () 
then do; 

call com_err_ (code, ME); 
return; ~" 
end /* then do */; 

/* WALK FRAMES TO FIND LAST ONE */ 

no frames =0; 

do"~sp s shp -> stack_header .stack_begin_ptr 
repeat sp -> stack_frame.n"ext sp 
while ( sp "s shp -"> stack_heao r er .stack_end__ptr) ; 
save_ptr = sp; 
no frames = no_frames + 1; 
end / T do sp */; " 

/* NOW TRACE BACKWARDS AND DUMP.*/ 
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GAINING DIRECT ACCESS TO SEGMENTS 
AN EXAMPLE 



do sp s save^ptr 

repeat sp -> stack frame.prev — sp 
while ( sp *= null T) ) ; 
call inter pret_ptr_ (sp -> stack frame. en try_ptr , sp, 

"" "" addr (ownerT); 
put skip (2) edit ("FRAME", no_frames, " IS OWNED BY " , 

rtrim( owner .segname) , rtrim( owner .entryname) ) 
(a,f(3) ,a,a ,a) ; 
put skip list (»• FRAME STARTS AT", sp) ; 

put skip list (" ARG POINTER IS", sp -> stack_frame.arg_ptr) ; 
no frames = no_frames -1; 
end /* do sp */; 

/* ALL DONE »/ 

put skip (2) list ("End stack_tracer") ; 

put skip; 

close file (sysprint); 

end /* stack_tracer */; 

r 14:08 0.237 6 
! stack_tracer 

FRAME 5 IS OWNED BY stack_tracer$st4ck t/acer 
FRAME STARTS AT pointer(234 !5o"40) 

ARG POINTER IS pointer(234 I5202 ) 

FRAME 4 IS OWNED BY command processor $comraand processor 
FRAME STARTS AT poTnter(234 !F000 ) 

ARG POINTER IS pointer(234 J4274 ) 

FRAME 3 IS OWNED BY abbrev$abbrev cp 

FRAME STARTS AT pointer(234 I2700 ) 

ARG POINTER IS pointer(234 !2564 ) 

FRAME 2 IS OWNED BY listen $listen__ 

FRAME STARTS AT pointer(234 I2400 ) 

ARG POINTER IS pointer(234 I2236 ) 

FRAME 1 IS OWNED BY initialize_process_$ initialize_process_ 
FRAME STARTS AT pointer(234 i20*00 ) 

ARG POINTER IS pointer(234 !0 ) 

End stack tracer 
r 14:09 07658 46 
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GAINING DIRECT ACCESS TO SEGMENTS 



AN EXAMPLE 



YOU ARE NOW READY FOR WORKSHOP 
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Topic VI MULTICS CONDITION MECHANISM Topic VI 

OBJECTIVES: 

Upon completion of this topic, students should be able to: 

1. Describe the actions taken by Multics when a condition is 
si anal led. 

2. Write handlers for the following conditions: 

cleanup 

prosram-interrupt 

finish 

User-defined and PL/1-defined conditions 

3. Write an "any_other" handler. 



4. Discuss the circumstances under which the system-defined 

*• r* r\M l f 1 nne rt *■ <• 1 1 ir 
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INTRODUCTION 



« thp MULTICS CONDITION MECHANISM IS A FACILITY THAT NOTIFIES A PROGRAM 
OF AN EXCEPTIONAL CONDITION 



I A CONDITION IS A STATE OF THE EXECUTING PROCESS 

J A CONDITION MAY OR MAY NOT INDICATE THAT AN ERROR HAS OCCURRED 



• IN MULTICS, THERE ARE THREE BROAD CATEGORIES OF CONDITIONS: 

I SYSTEM-DEFINED CONDITIONS (MULTICS LEVEL) 
Q ARE DEFINED AS PART OF THE MULTICS SYSTEM 
I ARE DETECTED BY THE MULTICS HARDWARE OR SOFTWARE 

n a op STr.UAiirn nv THF MI1T TTf!<? SltPFRVTSnR 

J| Alki^ fcJ XUilAyUU i* ** * ***** » * w** *, ^ v v -»-r.— — . — — — -- 

1 EXAMPLES 

I cleanup 

Q no_read_permission 

Q out_of__ bounds 

D quit 

Q record__quota__overflow - 

Q AND OTHERS, TO BE DISCUSSED LATER 
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INTRODUCTION 

a LANGUAGE-DEFINED CONDITIONS 
I ARE DEFINED AS PART OF PL/I 
I ARE DETECTED AND SIGNALLED BY THE PL/I RUNTIME PROCESSOR 

I EXAMPLES 

I conversion 

Q end file 

D AND OTHERS. . . 

D PROGRAMMER -DEFINED CONDITIONS 

II ARE DEFINED BY THE PROGRAMMER 

I ARE DETECTED AMD SIGNALLED EXPLICITLY BY THE PROGRAMMER 

I EXAMPLES 
1 oops 
Q OR WHATEVER ONE DESIRES... 
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INTRODUCTION 



* THE MULTICS CONDITION MECHANISM IS INVOKED WHEN A CONDITION IS DETECTED 
AND SIGNALLED BY: 



I THE SYSTEM 

I EXAMPLE: zerodivide OCCURS 

1 THE USER PROGRAM 

I EXAMPLE: "signal zerodivide;" 
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INTRODUCTION 



THE SIGNALLING OF A CONDITION: 



D IMMEDIATELY STOPS THE PROGRAM AT THE CURRENT POINT OF EXECUTION 



CAUSES A BLOCK ACTIVATION OF THE MOST RECENTLY ESTABLISHED ON 
UNIT FOR THAT CONDITION 

I THE APPROPRIATE ON UNIT IS FOUND BY MAKING A BACKWARDS TRACE 
OF THE STACK 

1 EACH BLOCK ACTIVATION ON THE STACK CAN HAVE ONLY ONE ON UNIT 
ESTABLISHED FOR EACH CONDITION AT ANY GIVEN TIME 



sub2$sub2 




sub1$sub1 


4 




main$main 


4 




coram and_proces so r_ 




abbrev 




listen^ 




initialize_process_ 





ON UNIT ESTABLISHED FOR zerodivide 



ON UNIT ESTABLISHED FOR zerodivide 



USER STACK 
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INTRODUCTION 



IF zerodivide IS SIGNALLED IN sub2, A BLOCK IS ACTIVATED FOR THE 
ON UNIT ESTABLISHED IN subl 



sub! $zerodivide.n 




(signal^) 




(pl1_signal_from_ops_) 




sub2$sub2 




subl $sub1 


i 




main$main 


i 




command_processor_ 




abbrev 




listen_ 




initial ize_process_ 





ON UNIT ESTABLISHED FOR zerodivide 



ON UNIT ESTABLISHED FOR zerodivide 



USER STACK 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 

* EXAMPLES OF ESTABLISHING CONDITION HANDLERS 
1 on zerodivide begin; 

• • * 

• • • 

end; 
I on zerodivide system; 

3 on zerodivide snap system; 

I IF THE CONDITION SPECIFIED IS SIGNALLED, THE 'probe' COMMAND 
IS IMMEDIATELY INVOKED BEFORE THE 'on unit' IS INVOKED (FOR 
AN ABSENTEE PROCESS, THE ' trace_stack' COMMAND IS EXECUTED) 

on zerodivide call probe; 



• THERE ARE THREE WAYS TO REVERT AN 'on unit' 



!I PL/I 'revert' STATEMENT (EXAMPLE: revert zerodivide;) 



D BLOCK DEACTIVATION CAUSED BY REACHING A BLOCK 'end' STATEMENT 



1 NON-LOCAL 'go to' WHICH CAUSES DEACTIVATION OF OF ALL BLOCKS 
FROM THE TOP OF THE STACK TO THE PROCEDURE CONTAINING THE LABEL 
THAT IS THE TARGET OF THE 'go to' 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 



This Page Intentionally Left Blank 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 



# EXAMPLE OF THE CONDITION MECHANISM 



example: proc; 


del 


subl external entry; 


del 


sub2 external entry; 


del 


overflow condition; 


on 


overflow <on unit 1>; 




call subl ; 




< statement 1>; 




call sub2; 


end 


/* example */; 



subl : proc; 

del overflow condition; 

< statement 2>; 

on overflow <on unit 2>; 

< statement 3>; 
end /* subl */; 



sub2: proc; 

del overflow condition; 

< statement 4>; 
on overflow <on unit 3>; 

< statement 5>; 

revert overflow; 

< statement 6>; 
end /* sub2 */; 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 



# ASSUME THAT EACH OF THE 6 NUMBERED STATEMENTS IN THE 3 PROCEDURES 
ON THE PREVIOUS PAGE IS A SIMPLE ASSIGNMENT STATEMENT (THERE ARE NO 
goto* s) 

FILL IN THE CHART SHOWING WHICH 'on unit' WOULD BE INVOKED IF 'overflow' 
OCCURRED IN THE NUMBERED STATEMENT SPECIFIED 

STATEMENT CAUSING overflow 

TO BE SIGNALLED ON UNIT INVOKED 

1 . 

2 

3 

4 

5 

6 
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A SPECIAL CATCH-ALL CONDITION HANDLER 



• THE 'any other' CONDITION REFERS TO CONDITIONS FOR WHICH NO 'on 
unit' HAS" BEEN SPECIFICALLY ESTABLISHED 



I EXAMPLE 

del (zerodivide, overflow, any_other) condition; 
on zerodivide begin; 

• • • 

end; 

on any__other begin; 

• • • 

end; 

signal overflow; 



BACKWARD TRACE OF STACK LOOKS FOR CONDITION HANDLER TWICE FOR 
EACH FRAME: 



I LOOKS FOR SPECIFIC CONDITION HANDLER FIRST 

D LOOKS FOR CONDITION HANDLER FOR 'any other' SECOND 



I THE 'cleanup' CONDITION IS AN EXCEPTION IN THAT IT DOES NOT 
INVOKE THE any_other HANDLER 
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ACTION TAKEN IF NO ? on unit 1 IS FOUND ON STACK 



• THERE IS A DEFAULT HANDLER 'default error handler • 



# THE PROGRAM, initialize process , HAS ONLY ONE 'on unit' (FOR THE 
CONDITION any_other) 



THE any_other CONDITION HANDLER CALLS default_error_handler_$wall 

default_error_handler_ CHECKS TO SEE WHICH CONDITION WAS SIGNALLED 

I EXECUTES DIFFERENT CODE BASED ON THE CONDITION 

I NOTIFIES USER IF IT WAS NOT SET UP TO HANDLE CONDITION (EXAMPLE: 
USER DEFINED CONDITIONS AND program_interrupt 

Q SEVERAL CONDITIONS RESULT IN CALL TO get_to_cl_$unclaimed_signal 
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ACTION TAKEN IF NO 'on unit' IS FOUND ON STACK 



listen_$release_stack 




get__to_cl__$unclaimed__signal 




d__e__h_$wall 


i 




any__other . 2 




signal_ 




pl1__signal__from_ops_ 




user_prog 


4 




coram and__processor_ 




abbrev 




listen_ 




initial ize__process_ 


4 





ON UNIT ESTABLISHED FOR any_other 



SIGNAL XYZ 



ON UNIT ESTABLISHED FOR any other 
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ACTION TAKEN IF NO 'on unit* IS FOUND ON STACK 



default_error_handler $wall SETS UP CONDITION HANDLER FOR any__other 
THAT RESULTS IN A CALL TO default_error_handler_$wall_ignore_pi 



THUS, A "CONDITION WALL" IS SET UP BETWEEN PROGRAMS RAISING 
CONDITIONS THAT HAVE NO HANDLERS FOR THEM & PROGRAMS RUN AT A 
NEW COMMAND LEVEL THEREAFTER 



I THE WALL IS TRANSPARENT TO THE ' program_interrupt' AND 'finish' 
CONDITIONS 
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'program interrupt' CONDITION 



THE PSEUDO CODE FOR program_interrupt IS AS FOLLOWS: 

program^ interrupt : pi: proc; 

del prograra^interrupt condition; 

del signal__~"entry options (variable); 

del start entry options (variable); 

call signal_ ( n program__interrupt n , ...); 

if handler_was__ found 

then call start; 

else call com_err_ (..., n program_interrupt n , "There is no suspended 

™ invocation of a subsystem that supports the use of 
this command .") ; 

end /* program_interrupt */; 
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'program interrupt' CONDITION 



EXAMPLE DEMONSTRATING THAT » program_interrupt' "PENETRATES THE WALL" 

handler: proc; 

del (program_interrupt , 

quit, 

zerodivide) condition; 

del sysprint file; 

on zerodivide go to A; 

on program_interrupt go to B; 

signal quit; 

A: put skip list ("ZERODIVIDE HAPPENED"); 

put skip; 
B: put skip list ("PROGRAM INTERRUPT HAPPENED"); 

put skip; 

end /* handler */; 

r 14:52 0.153 2 

! handler 
QUIT 
r 14:52 0.265 3 level 2 

! signal zerodivide 

Error: Attempt to divide by zero at signal$ 11101 
( > system_libr ar y_st and ard> bo und_command_en v_) 
system handler for error returns to command level 
r 14:52 0.524 20 level 3 

• signal prcgram_interrupt 

PROGRAM INTERRUPT HAPPENED 
r 14:52 0.221 7 
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PARTIAL STACK HISTORY OF EXAMPLE 



LISTEN. 





(SIGNAL OUIT> 


LIITCM. 




UNCLAMCD.EIGNAL 




9.E.H.SWALL 




ANV.OTHER.1 




SIGNAL. 




r-LI.SIG.FROM Ott. 


HANDLER 


mi^i 


«-'. 




AISHEV 




I 



SIGNAL 
1ERODIVIOE 





SIGNAL 

PROGRAM 

INTERRUri 

»- 


HANDLERS*! 


<BOIOI;> 






tISNAl. 






SIGNAL 






e_r_ 






ASSREV 




IIIIEK. 




UNCLAIMED.SIGNAL 


UNCLAIMED. SIGNAL 

.VALL IGNORE, PI . 
ANY OTHER 1 
SIGNAL. 




WAll_l8N0RE.fi. 
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'program interrupt* CONDITION 



• NOTE: 'any other' CONDITION HANDLERS SHOULD PASS ON THE 

•program interrupt' CONDITION (SEE continue_to_signal_ AND 
find condition info ) 
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SUMMARY OF CONDITION HANDLING MECHANISM 



CONDITION X RAISED 



EXAMINE MOST 

RECENT 

ACTIVATION 



EXAMINE NEXT 

PREVIOUS 

ACTIVATION 



NO 



4- 



IS THERE A HANDLER 
ESTABLISHED IN THIS 
ACTIVATION FOR 
CONDITION X? 



NO 



I 



YES 



INVOKE THE 
HANDLER 



a 



YES 



IS THERE A DEFAULT 
HANDLER ESTAB- 
LISHED IN THIS 
ACTIVATION FOR 
ANY OTHER? 



I 



NO 




IS THIS THE 

OLDEST 

ACTIVATION? 



I 



YES 



DOES HANDLER 
WANT SEARCH 
CONTINUED? 



YES 



NO HANDLER 
FOR THIS 
CONDITION 



I 



NO 



RETURN 
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REVIEW OF PL/I DEFINED CONDITIONS 





Default Error 
Handler Signals 
Error 


Undefined if hit 
End of On Unit 


Can be Enabled/ 
Disabled 


Disabled by 
Default 


area 


X 


X 






error 


(X) 


X 






storage 


X 


X 






fixedoverflow 


X 


X 


X 




overflow 


X 


X 


X 




size 


X 


X 


X 


X 


stringrange 


X 


X 


X 


X 


subscriptrange 


X 


X 


X 


X 


zerodivide 


X 


X 


X 




conversion 


X 




X 




endftie 


X 








key 


X 








record 


X 








transmit 


X 








undefined file 


X 


*" 






underflow 






X 




stringsize 






X 


X 


name 










endpage 










finish 











NOTE THAT THE 'size' CONDITION IS ENABLED DURING PL/I I/O 
(pl1 signal from ops ), AND CONSEQUENTLY, A PL/I PROGRAM WHICH IS 
EXECUTING r put' "STATEMENTS TO THE 'sysprint' FILE MAY CAUSE 'size' 
CONDITIONS TO BE SIGNALLED EVEN THOUGH THE CONDITION IS NOT ENABLED IN 
THE PROGRAM ITSELF 
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REVIEW OF PL/I DEFINED CONDITIONS 



• CONDITIONS IN THE PRECEDING TABLE WERE COVERED IN EARLIER COURSES, 
HOWEVER, THE 'finish', 'area' AND 'storage' CONDITIONS ARE COVERED 
BELOW SINCE THEY ARE NOT USUALLY FULLY UNDERSTOOD IN AN INTRODUCTORY 
COURSE 



I 'finish' CONDITION 

1 THE FINISH CONDITION IS SIGNALLED JUST PRIOR TO RUN UNIT OR 
PROCESS TERMINATION 

I IT IS SIGNALLED BY A STOP STATEMENT OR BY COMMANDS SUCH AS 
•stop_run', 'logout' AND 'new_proc' 

Q IT BEHAVES JUST LIKE 'program interrupt' IN THAT IT "PENETRATES 
THE WALL" 

ALL CONDITION HANDLERS, WHETHER THEY HANDLE 'finish' OR NOT, 
SHOULD PASS THIS CONDITION ON (BY CALLING continue to_signal__) 
SO THAT ALL PROGRAMS WILL BE NOTIFIED OF THE IMPENDING PROCESS, 
OR RUN UNIT, DESTRUCTION 
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REVIEW OF PL/I DEFINED CONDITIONS 



D 'area* CONDITION 



1 AN ATTEMPT HAS BEEN HADE TO ALLOCATE STORAGE IN A PL/I •area* 
VARIABLE WHICH DOES NOT HAVE SUFFICIENT STORAGE FOR THE ATTEMPTED 
ALLOCATION 



I PRINTS A MESSAGE AND SIGNALS THE ERROR CONDITION 



1 EXAMPLE 



del (p,q,r) ptr; 

del (A,B) (1000) fixed bin based; 
del C area(2000) static; 
d float bin based; 



del 



allocate A set(p) in(C); 

• • m t 

allocate d set(q) in( C) ; 

• • • 

allocate B set(r) in(C); 

causes 'area* condition (unless intervening 
'free 1 statements were executed) */ 



D 'storage 1 CONDITION 



1 AN ATTEMPT HAS BEEN MADE TO GROW A STACK SEGMENT PAST ITS 
MAXIMUM LENGTH 



I GENERALLY OCCURS AS A RESULT OF ATTEMPTING TO GENERATE A LARGE 
AMOUNT OF 'automatic' STORAGE, OR AS A RESULT OF A RUNAWAY 
RECURSIVE PROCEDURE 



I IS ALSO SIGNALLED IF A PL/I PROGRAM OVERFLOWS THE SYSTEM FREE 
STORAGE AREA 
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SOME SYSTEM-DEFINED CONDITIONS 



THE MULTICS SYSTEM HAS DEFINED SOME CONDITIONS OF ITS OWN 



• SOME OF THE USEFUL SYSTEM-DEFINED (NON-PL/I) CONDITIONS ARE LISTED 
BELOW: 



I active_function_error , command_error 

fl ARE SIGNALLED BY THE active fnc_err_ AND com_err_ SUBROUTINES 
RESPECTIVELY 

I DEFAULT HANDLER FOR command_error PRINTS A MESSAGE AND RETURNS 

II DEFAULT HANDLER FOR active function_error PRINTS AN ERROR 
MESSAGE AND RETURNS TO A NEW~COMMAND LEVEL 



I cleanup 

D SIGNALLED TO THOSE PROCEDURES OWNING STACK FRAMES TO BE DISCARDED 
AS A RESULT OF A NON-LOCAL TRANSFER 

I THIS IS A VERY ATYPICAL USE OF THE CONDITION MECHANISM, SINCE 
•cleanup' IS SIGNALLED IN EVERY FRAME BETWEEN THE CURRENT 
STACK FRAME AND THE FRAME CONTAINING THE TARGET OF THE NON-LOCAL 
TRANSFER 

I TYPE OF THING USUALLY DONE IN A 'cleanup' HANDLER 

I CLOSE FILES WHICH HAD BEEN OPENED IN THAT ACTIVATION BLOCK 
1 FREE ALLOCATED 'controlled* OR 'based' VARIABLES 
1 REINITIALIZE STATIC VARIABLES 
H SHOULD NOT DO A NON-LOCAL ' goto ' 

THIS WOULD INTERFERE WITH THE ONE ALREADY IN PROGRESS 
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SOME SYSTEM-DEFINED CONDITIONS 



fault_tag_1 

I SIGNALLED WHEN AN ATTEMPT IS MADE TO ACCESS THROUGH AN 
UNINITIALIZED POINTER OR A POINTER CONTAINING INVALID DATA 



I illegal__opcode, illegal_procedure 

SIGNALLED WHEN AN ATTEMPT IS MADE TO EXECUTE AN INVALID OR 
PRIVILEGED MACHINE INSTRUCTION 



H linkage_error • 

D SIGNALLED WHEN THE DYNAMIC LINKING MECHANISM OF MULTICS CAN 
NOT LOCATE AN EXTERNAL OBJECT 



! . lockup 

U STfiMiU T Fn UHFM A PBOnRAM T<I rVPrrtTTxrr- A ttput rnnn nj? /irtrsr- 
- — — — -• — — — — ' ..•«—»■ ii » *» w^Akfkt 4 j.w l. ai-» ^ \j i. i,ii \j ix i xvjn i uuu r ur ^uut 

FOR TOO LONG A TIME 



I null_pointer 

B SIGNALLED WHEN AN ATTEMPT IS MADE TO USE AN INVALID (NULL) 
POINTER 



I out__of_bounds 

D SIGNALLED WHEN AN ATTEMPT IS MADE TO REFER TO A LOCATION 
BEYOND THE CURRENT LENGTH OF A SEGMENT 
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SOME SYSTEM-DEFINED CONDITIONS 



I program_interrupt 

SIGNALLED WHEN THE USER HAS ISSUED THE 'program_interrupt » 
COMMAND 



I quit 

SIGNALLED WHEN THE USER HITS THE 'break' OR 'attention' KEY 
ON HIS/HER TERMINAL (THE DEFAULT HANDLER PRINTS THE WORD "QUIT" 
ON THE USER'S TERMINAL, ABORTS THE PROGRAM, AND ESTABLISHES A 
NEW COMMAND LEVEL) 

D IN GENERAL, USER PROGRAMS SHOULD NOT HANDLE THE 'quit' CONDITION 



I record__quota_over flow 

D SIGNALLED WHEN A USER ATTEMPTS TO ALLOCATE A RECORD IN SECONDARY 
STORAGE WHICH WILL OVERFLOW HIS/HER ALLOTTED LIMIT 



I seg_fault_ error 

SIGNALLED WHEN AN ATTEMPT IS MADE TO USE A POINTER WITH AN 
INVALID SEGMENT NUMBER, AND CAN BE CAUSED BY: 

I THE DELETION OR TERMINATION OF A SEGMENT AFTER THE POINTER 
IS INITIALIZED 

1 THE POINTER IS NOT INITIALIZED IN THE CURRENT PROCESS 
I THE USER HAS NO ACCESS TO THE SEGMENT 
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SOME SYSTEM-DEFINED CONDITIONS 



YOU ARE NOW READY FOR WORKSHOP 
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Topic VII THE MULTICS I/O SYSTEM Topic VII 

OBJECTIVES: 

Upon completion of this topic* students should he able to! 

1. Define the following terms! 

I/O switch 

I/O module 

stream I/O 

record sequential I/O 

record blocked I/O 

indexed I/O 

2. List the more popular I/O modules. 

3. List the steps required to perform I/O. 

4. Describe an I/O control block < IOCS ) . 
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CHARACTERISTICS 



• THE MULTICS INPUT/OUTPUT SYSTEM IS A FLEXIBLE, GENERALIZED I/O SYSTEM 
CAPABLE OF SUPPORTING SEVERAL PROTOCOLS OF DATA TRANSMISSION TO A 
FULL COMPLEMENT OF FILES AND DEVICES 



I/O SYSTEM BASIC CHARACTERISTICS: 



I LOGICAL INPUT/OUTPUT REQUESTS ARE USED RATHER THAN DEVICE-SPECIFIC 
PHYSICAL REQUESTS 



11 DEVICE INDEPENDENCE IS ACHIEVED VIA THE MULTICS I/O SWITCH MECHANISM 



I! UNFAMILIAR OR NEW DEVICES CAN BE ADDRESSED VIA THE IMPLEMENTATION 
OF SITE-PREPARED INPUT/OUTPUT INTERFACE MODULES 
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THE MULTICS I/O MECHANISM 



• THE I/O MECHANISM USES THE FOLLOWING CONSTRUCTS: 



I SWITCH, SWITCHNAME 

1 A SWITCH IS A LOGICAL CONSTRUCT USED TO DESIGNATE THE TARGET 
OF AN INPUT OR OUTPUT REQUEST 

I ASSOCIATED WITH AN I/O SWITCH IS A "SWITCHNAME" 

ALL I/O REQUESTS ARE DIRECTED TO A "SWITCH" WHICH IS "ATTACHED" 
BY A DEVICE-DEPENDENT PROGRAM, CALLED AN I/O MODULE, TO A 
PARTICULAR DEVICE OR FILE 

1 THE SUPPORTING DATA STRUCTURE OF A SWITCH IS AN I/O CONTROL 
BLOCK (IOCB) 



INPUT/OUTPUT MODULE 

II A DEVICE-DEPENDENT COMMUNICATION MODULE WHICH ACTS AS THE 
INTERFACE BETWEEN THE USER'S LOGICAL I/O REQUESTS AND THE 
HARDWARE-LEVEL I/O SYSTEM 

I TRANSLATES THE USER'S LOGICAL REQUESTS INTO THE PHYSICAL REQUESTS 
APPROPRIATE TO THE TYPE OF DEVICE OR FILE FOR WHICH IT WAS 
WRITTEN 

I SYSTEM STANDARD MODULES SUPPORT I/O TO/ FROM BASIC DEVICES (TAPE, 
REMOVABLE DISK, TERMINAL DEVICES, CARD READERS, ETC.) AND 
FILES (SEGMENTS IN THE VIRTUAL MEMORY) 
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THE MULTICS I/O MECHANISM 





[ discard_l 
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THE MULTICS I/O MECHANISM 
PROTOCOLS SUPPORTED 



• FOUR BASIC I/O PROTOCOLS (FILE STRUCTURES) SUPPORTED 



I THE TYPE OF PROTOCOL BEING USED LIMITS THE REQUESTS THAT CAN BE 
SATISFIED 



I CERTAIN I/O MODULES SUPPORT ONLY ONE PROTOCOL, SOME I/O MODULES 
SUPPORT ALL THE PROTOCOLS 



11 THEY ARE: 



II 1) STREAM INPUT/OUTPUT 

I A STREAM FILE IS A SEQUENCE OF ASCII CHARACTERS, SEPARATED 
BY NEWLINE AND NEWPAGE CHARACTERS 

I OFTEN CALLED AN "UNSTRUCTURED" FILE 

I EXAMPLES: TERMINAL DIALOG, TEXT EDITOR CREATED SEGMENTS, 
TAPES WRITTEN VIA tape_mult_ 

D 2) RECORD SEQUENTIAL INPUT/OUTPUT 

I A "STRUCTURED" FILE OF VARIABLE LENGTH RECORDS, EACH RECORD 
REPRESENTING ONE STRUCTURE 

1 A RECORD FILE MAY BE ACCESSED IN "SEQUENTIAL" PROTOCOL, 
WHICH MEANS THAT THE CURRENT RECORD AND NEXT RECORD ARE 
WELL-DEFINED 

I EXAMPLES: TAPES WRITTEN VIA tape ibm OR tape ansi .CERTAIN 
VIRTUAL MEMORY SEGMENTS ~ - - 
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THE MULTICS I/O MECHANISM 
PROTOCOLS SUPPORTED 



D 3) RECORD BLOCKED INPUT/OUTPUT 

1 A RECORD FILE MAY BE CREATED IN LOGICAL BLOCKS, THUS ALLOWING 
I/O TO BE DONE A BLOCK AT A TIME 

I BLOCK SIZE IS FIXED 

II A BLOCK CONTAINS 

I ONE RECORD (WITH POTENTIAL WASTED SPACE) IF IN A VIRTUAL 
MEMORY FILE 

I ONE OR MORE RECORDS IF ON ANSI OR IBM TAPE 

1 SPECIFY BLOCKED MODE AT ATTACH TIME 

I 4) INDEXED INPUT/OUTPUT 

I AN INDEXED FILE IS A "KEYED" FILE, IMPLEMENTED AS A 
MULTI-SEGMENT FILE WITH ONE (OR MORE) COMPONENTS HOLDING 
THE "KEY VALUES", AND ONE (OR MORE) COMPONENTS HOLDING THE 
"DATA RECORDS" 

AN INDEXED FILE MAY BE ACCESSED IN EITHER "KEYED SEQUENTIAL" 
MODE. OR "KEYED DIRECT" MODE 

1 MUST BE IN THE VIRTUAL MEMORY 

I EXAMPLE: "RELATIONS" IN A MRDS DATABASE 



I PL/I DEDUCES THE PROTOCOL BY EXAMINING LANGUAGE I/O STATEMENTS 
AND/OR THE ATTACH DESCRIPTION 
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THE MULTICS I/O MECHANISM 
THE MORE POPULAR I/O MODULES 



# SOME OF THE SYSTEM STANDARD I/O MODULES, THEIR FUNCTIONS, AND THE 
PROTOCOLS SUPPORTED ARE: 



NAME 

1) vfile_ 

2) tty_ 

3) discard_ 

4 ) syn__ 

5) rdisk_ 

6) record_ stream_ 

7) -tape__mult_ 

8) tape_ibm_ 
tape~ansi_ 

9) tape_nstd_ 

10) bisync_ 

11) audit 



FUNCTION 

I/O TO/ FROM SEGMENTS IN 
THE VIRTUAL MEMORY 

I/O TO/FROM TERMINAL 
DEVICES 

OUTPUT SINK 

ALLOWS ONE SWITCH TO SERVE 
AS A SYNONYM FOR ANOTHER 
SWITCH 

I/O TO/ FROM REMOVABLE, NON- 
MULTICS DISK PACKS 



ALLOWS RECORD I/O OPERATIONS 
TO BE DIRECTED TO A STREAM 
FILE AND VICE VERSA 

I/O TO/ FROM A MULTICS 
FORMAT TAPE 

I/O TO/ FROM A TAPE FILE IN 
IBM OR ANSI FORMAT 



PROTOCOLS SUPPORTED 



ALL 
STREAM 

ALL 

ALL 



SEQUENTIAL, 
KEYED, OR 
BLOCKED 

STREAM 
<-> 

SEQUENTIAL 

STREAM 



SEQUENTIAL, 
BLOCKED 



I/O TO/FROM TAPES IN NON-STANDARD SEQUENTIAL 
OR UNKNOWN FORMATS 

I/O ACROSS A BINARY SYNCHRONOUS STREAM 

COMMUNICATIONS CHANNEL 

INTERCEPTS I/O ACTIVITY ON A STREAM 

GIVEN SWITCH, ALLOWING LOGGING 
AND EDITING OF DATA 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/O 



• STEPS REQUIRED TO PERFORM I/O 



1) THE SPECIFIED SWITCH MUST BE "ATTACHED" (INITIALIZED) BY A 
SPECIFIED I/O MODULE TO SOME TARGET DEVICE OR FILE (SUBSEQUENT 
REQUESTS DIRECTED TO THE SWITCHNAME OPERATE VIA THE I/O MODULE 
ON THE TARGET DEVICE OR FILE) 



2) THE SWITCH MUST BE "OPENED" IN A MODE COMPATIBLE WITH THE 
TYPE OF DEVICE OR FILE BEING MANIPULATED 



3) INPUT/OUTPUT OPERATIONS CAN NOW BE DIRECTED TO THE SWITCH 
(OPERATIONS MUST BE CONSISTENT WITH THE ATTACHMENT AND OPENING 
MODE OF THE SWITCH) 



4) THE SWITCH MUST BE "CLOSED" LEAVING THE SWITCH IN THE STATE 
IT WAS PRIOR TO THE "OPENING" (THAT IS, IT MAY NOW BE OPENED 
WITH A DIFFERENT MODE) 



5) THE SPECIFIED SWITCH MUST BE "DETACHED" BREAKING THE ASSOCIATION 
BETWEEN THE SWITCHNAME AND THE I/O MODULE AND TARGET (HENCE, THE 
SWITCH MAY BE ATTACHED IN A NEW WAY) 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/O 




SWITCH 


OPEN 


IOCB 


MODE i : 





\ \ \ \ 
\ \ \ \ 



O O 
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THE MULTICS I/O MECHANISM 



PERFORMING MULTICS I/O 



• ALL I/O OPERATIONS CAN BE PERFORMED AT THREE BASIC LEVELS: 

I LANGUAGE LEVEL - 'open', 'close', 'get', 'read', 'put', 'write 1 

COMMAND LEVEL - THE »io_call' COMMAND 

II SUBROUTINE LEVEL - THE «iox_' SUBROUTINE 

1 EXAMPLES (THE FOLLOWING ARE EQUIVALENT): 

1 PL/I 

open file ( x) title ("vfile__ user_file") stream output; 



It rnuumtn t nrci 
U \^ unri n n u uCi vbJ^ 

io_call attach x vfile_ user_file 
io~call open x stream_output 



SUBROUTINE LEVEL 

call iox_$attach_nanie ("x", iocb_ptr , "vfile_ user^file" , 

ref — ptr, code); 
call iox_$open (iocb_ptr, 27 n 0"b, code); 



I LANGUAGE VS. I/O SYSTEM 



PL/I STATEMENT 



open 



close 



EQUIVALENT I/O CALLS 



attach 
open 



close 
detach 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/O 



• THE ATTACHMENT AND DETACHMENT OF A SWITCH CAN BE PERFORMED EITHER 
EXTERNALLY TO A PROGRAM OR INTERNALLY BY THE PROGRAM ITSELF 



I IF THE SWITCH IS ATTACHED EXTERNALLY, THE PROGRAM RECOGNIZES 
THIS ATTACHMENT, HONORS THIS PRIOR ATTACHMENT, AND IGNORES THE 
SPECIFIED INTERNAL ATTACH DESCRIPTION (THUS YIELDING DEVICE 
INDEPENDENCE) 



IF THE SWITCH HAS NOT BEEN ATTACHED EXTERNALLY, THE ATTACH 
DESCRIPTION SUPPLIED BY THE PROGRAM (EITHER EXPLICITLY OR 
IMPLICITLY) WILL BE USED TO ATTACH THE SWITCH 



I IF THE SWITCH IS ATTACHED EXTERNALLY, IT MUST BE DETACHED EXTERNALLY 

I IF THE SWITCH- IS ATTACHED INTERNALLY BY EXECUTION OF THE 'open' 
STATEMENT, IT WILL BE DETACHED BY EXECUTION OF THE 'close' 
STATEMENT 



• THE ABOVE STATEMENTS SIMILARLY APPLY TO THE OPEN AND CLOSE OPERATIONS 
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II EXAMPLE 



THE MULTICS I/O MECHANISM 



PERFORMING MULTICS I/O 



x: proc; 

del line char(80); 
del (abc, xyz) file; 
del i; 

open file (abc) input; 
open file (xyz) output; 

do i = 1 to 50; 

get file (abc) list (line); 

put file (xyz) list (line); 
end; 

close file (abc), file (xyz); 

end /* x */; 



1 TO HAVE OUTPUT. SENT TO TERMINAL INSTEAD OF FILE xyz USER COULD 
TYPE THE FOLLOWING: 



! io — call attach xyz syn_ user_output 
! x 



! . io_call detach xyz 
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THE 'iox ' SUBROUTINE 



• iox IS THE USER-RING INTERFACE TO THE MULTICS INPUT/OUTPUT SYSTEM 



I ALL I/O OPERATIONS ISSUED AT THE USER-RING LEVEL (WHETHER FROM 
COMMAND LEVEL, LANGUAGE LEVEL, OR DIRECT iox__ CALL) RESULT IN A 
CALL TO iox ** 



D iox PROVIDES ENTRY POINTS FOR ALL INPUT/OUTPUT OPERATIONS 



I EVERY iox ENTRY POINT REQUIRES AN ARGUMENT DENOTING THE PARTICULAR 
I/O SWITCH (ACTUALLY THE IOCB) INVOLVED IN THE OPERATION 



I IF AN ENTRY POINT REQUIRES THE I/O SWITCH TO BE OPEN, AND IF IT 
IS NOT, THE CODE 'error_table_$not_open' IS RETURNED 



I IF THE I/O SWITCH IS OPEN, BUT THE OPERATION IS NOT ALLOWED FOR 
THAT OPENING MODE, THE CODE » error_table_$ reoperation' IS RETURNED 
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THE 'iox ' SUBROUTINE 

• THE MAJOR ENTRY POINTS OF iox_ CAN BE CLASSIFIED AS FOLLOWS: 

I ATTACHING/DETACHING 

I iox_$attach_name 

fl iox_$attach_ptr 

fl iox__$detach__iocb 

Q iox_$destroy_iocb 

Q iox__$find_iocb 

fl iox_$look_iocb 

Q iox — $move__attach 

fl OPENING/CLOSING 
I iox_$open 
fl iox_$ close 

fl STREAM I/O REQUESTS 

I iox_$get_chars 
Q iox_$get_line 

II iox_$put_chars 
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THE 'iox ' SUBROUTINE 



D RECORD I/O REQUESTS 

I iox_$delete_record 

D iox_$read_key 

B iox_$read_length 

D iox_$read — record 

i iox_$rewrite_record 

iox_$seek_key 

Q iox_$write_record 

D CONTROL REQUESTS 

1 iox_$ control 
iox_$ modes 

D iox_$ position 
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I/O CONTROL BLOCKS 



« WHAT IS AN I/O CONTROL BLOCK (IOCB)? 



Q EVERY SWITCHNAME HAS ASSOCIATED WITH IT AN 'IOCB' 



Q AN 'IOCB' IS A STANDARD DATA STRUCTURE 



H IT IS THE PHYSICAL REALIZATION OF A SWITCH 



1 THEY ARE FOUND IN THE USER'S PROCESS DIRECTORY 



AN 'IOCB' IS CREATED BY iox WHEN A SWITCHNAME IS USED IN AN 
"ATTACH STATEMENT" OR "ATTACH COMMAND" FOR THE FIRST TIME IN A 
PROCESS 



I IF THE SAME SWITCHNAME IS USED LATER IN THE PROCESS, THE SAME 
'IOCB* IS REUSED 



I THUS THERE IS A ONE TO ONE MAPPING BETWEEN SWITCHNAMES AND 
IOCB'S 



I ONCE AN 'IOCB' IS CREATED, IT LIVES THROUGHOUT THE PROCESS (UNLESS 
EXPLICITLY DELETED) 
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I/O CONTROL BLOCKS 



/» BEGIN INCLUDE FILE iocb.incl.pl1 

13 Feb 1975, M. Asherman */ 
/* Modified 11/29/82 by S. Krupp to add new entries and 

to change version number to 10X2. */ 
/* format: style2 */ 

del 1 iocb aligned based, 

/* I/O control block. */ 
2 version character (4) aligned, 

/• 10X2 */ 
2 name char (32) , 

/* I/O name of this block. */ 
2 actual iocb_ptr ptr, 

/• IOCB ultimately SYNed to. */ 
2 attach_descrip_ptr ptr, 

/* Ptr to printable attach description. */ 
2 attach_data_ptr ptr , 

/* Ptr to - attach data structure. */ 
2 open__descrip__ptr ptr, 

/* Ptr to "printable open description. */ 
2 open — data__ptr ptr , 

/•""Ptr "Eo open data structure (old SDB) . */ 
2 reserved bit (72), 

/• Reserved for future use. */ 
2 detach_iocb entry (ptr, fixed (35)), 

/• detach_iocb(p,s) */ 
2 open *~ entry (ptr, fixed, bit (1) aligned, 

fixed (35)) , 

/* open( p,mode,not_used ,s) */ 
2 close entry (ptr, fixed (35)), 

/* close(p,s) */ 
2 get line entry (ptr, ptr, fixed (21), 

fixed (21), fixed (35)) , 

/* get_line( p,bufptr ,buflen ,actlen,s) */ 
2 get char's entry (ptr, ptr, fixed (21), 

fixed (21), fixed (35)) , 

/* get_chars( p,bufptr ,buflen ,actlen ,s) */ 
2 put chars entry (ptr, ptr, fixed (21), 

fixed (35)) , 

/* put__chars( p,bufptr ,buflen ,s) */ 
2 modes "" entry (ptr, char (*), char (•), 

fixed (35)) , 

/• modes( p,newmode,oldmode,s) */ 

2 nnsihinn Anti*v ( n+.ir . fiirpri. fiypH ( ? 'M . 

— r"" — — -"rf » r - • 7 i ,— .,, 

fixed (35)) , 
/• position(p,u1 ,u2,s) */ 
2 control entry (ptr, char (*), ptr, 

fixed (35)) , 
/* controK p, order ,infptr ,s) •/ 
2 read record entry (ptr, ptr, fixed (21), 

fixed (21 ) , fixed (35)) , 
/* read_record( p,buf ptr ,buflen ,actlen ,s) •/ 
2 write^record entry (ptr, ptr, fixed (21), 
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I/O CONTROL BLOCKS 



fixed (35)) , 
/* write_record( p,bufptr ,buflen ,s) */ 
2 rewrite record .entry (ptr, ptr, fixed (21), 

fixed (35)) , 
/* rewrite_ > record(p,bufptr ,buflen ,s) */ 
2 delete_record entry (ptr, fixed (35)), 

/* deiete_record(p,s) */ 
2 seek_key entry (ptr, char (256) varying, 

fixed (21), fixed (35)) , 
/* seek_key( p,key,len ,s) */ 
2 read key entry (ptr, char (256) varying, 

fixed (21), fixed (35)) , 
/* read_key( p,key,len ,s) */ 
2 read_length entry (ptr, fixed (21), fixed (35)), 

/*~read_length( p,len,s) */ 
2 open file - entry (ptr, fixed bin, char (*), 

bit (1) aligned, fixed bin (35)), 
/* open_file( p,mode,desc ,not_used ,s) */ 
2 close__file entry (ptr, char (*), fixed bin (35)), 

/* close_file( p,desc ,s) */ 
2 detach ~* entry (ptr, char (*), fixed bin (35)); 

/* detach( p,desc ,s) */ 

declare iox_$iocb_version_sentinel 

~~ character (4) aligned external static; 

/* PMn TMPT Iini? JTTT IT i noh innl nl 1 */ 

, wilt* j.«wuwvu » .»*<». . . . . . ---- .-...-.» , r » , ..... , 

del 1 attach descrip based aligned, 
2 length fixed bin (17) , 

2 string char (0 refer (attach descrip. length) ) ; 
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I/O CONTROL BLOCKS 



• AN ATTACH DESCRIPTION IS A CHARACTER STRING CONVEYING THE FOLLOWING 
INFORMATION: 



I MODULE NAME 

I MODULE-SPECIFIC ARGUMENTS, SUCH AS: 
I PATHNAME (vfile_) 
D CHANNEL NAME (tty_, bisync_) 

Q VOLUME ID (tape_ibra_, tape_ ansi_, tape_mult_, tape_nstd_) 
D DISKJ)RIVE_ID AND PACK_ID (rdiskj 
D SWITCHNAME (syn_, record - stream_) 

Q MODULE-SPECIFIC CONTROL ARGUMENTS, SUCH AS: 
I -extend (vfile_, tape_ ibm_, tape_ansi__) 
fl -density (tape^ibm^ , tape_ansi_, tape_mult_) 
-block (tape_ibm__; tape_ansi_) 
-blocked (vfile ) 



COMPLETE DESCRIPTIONS OF THE I/O MODULES AND THE ARGUMENTS SPECIFIED 
AT ATTACH TIME ARE IN Multics Subroutines & I/O Modules (AG93) 
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I/O CONTROL BLOCKS 



• THE PRINCIPAL COMPONENTS OF AN 'IOCB» ARE 'pointer' VARIABLES AND 
•entry' VARIABLES 



• THERE IS ONE 'entry' VARIABLE FOR EACH I/O OPERATION, WITH THE 
EXCEPTION OF THE ATTACH OPERATION 



TO PERFORM AN I/O OPERATION THROUGH THE SWITCH, THE APPROPRIATE 
ENTRY VALUE IN THE CORRESPONDING 'IOCB' IS CALLED 



I FOR EXAMPLE: 

call iox__ $put_chars( iocb_ ptr , ) ; 

CAN BE THOUGHT OF AS: 

call iocb__ptr->iocb ,put_chars( ) ; 
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I/O CONTROL BLOCKS 



WHEN iox $ attach name IS CALLED IT: 



I CREATES/LOCATES THE »IOCB» ASSOCIATED WITH THAT SWITCHNAME 



I INITIALIZES SOME OF THE ELEMENTS IN THE , IOCB» STRUCTURE 



II CALLS <module n am e>$< module name> attach 



D THUS THERE NEED BE NO ENTRY FOR THE ATTACH OPERATION IN THE 
•IOCB' 



THIS ENTRY POINT IN THE I/O MODULE FINISHES THE INITIALIZATION 
OF THE 'IOCB' 



FOR EXAMPLE, IF THE I/O MODULE INVOLVED IN THE ATTACHMENT WAS 
vfile : 



I vfile_$vfile_attach IS CALLED 

I AFTER THE ATTACHMENT (INITIALIZATION) IS COMPLETE: 
I iocb.open CONTAINS THE ENTRY TO vfile_$open 
Q iocb. close CONTAINS THE ENTRY iox_$err_not_open 
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I/O CONTROL BLOCKS 



• AFTER THE ATTACHMENT OF THE SWITCH, EVERY I/O OPERATION ON THAT 
SWITCH REFERENCES THE CORRESPONDING 'IOCB' TO FIND THE ENTRY POINT 
AT WHICH TO START EXECUTION 



I ONE OF TWO ACTIONS MAY RESULT: 



I iox GENERATES AN ERROR MESSAGE (IF IT IS AN ILLEGAL OPERATION) 



EXECUTION STARTS AT THE APPROPRIATE ENTRY POINT OF THE 
APPROPRIATE MODULE 

I THIS EXECUTION UPDATES THE 'IOCB', USUALLY REPLACING SOME 
ENTRY VALUES CAUSING ERROR MESSAGES WITH ENTRY VALUES 
INDICATING ENTRY POINTS IN THE MODULE (AND VISA VERSA) 

EXAMPLE (IN THE ABOVE CASE): 



IOCB MEMBER 


BEFORE OPENING 


AFTER OPENING 


iocb .open 


vfile_$open 


iox_$ er r_no t_cl o sed 


iocb. close 


iox_$err_not_open 


vfile_$ close 



• IT IS THE RESPONSIBILITY OF THE I/O MODULE TO MAINTAIN THE ACCURACY 
OF THE 'IOCB' 



# ONLY THE iox ENTRY POINTS RESULTING IN ATTACHMENT OF A SWITCH 
REQUIRE THE MODULE AS AN INPUT ARGUMENT 



I AFTER THAT TIME, THE 'IOCB 1 "POINTS TO" THE APPROPRIATE ENTRY 
POINTS IN THE APPROPRIATE MODULE (THE USER NEED ONLY PROVIDE A 
POINTER TO THE 'IOCB') 
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I/O CONTROL BLOCKS 



# IN VIEW OF THE ABOVE DISCUSSION OF IOCB'S AND SWITCHES, THE TERM 
"SWITCH" SHOULD MAKE MORE SENSE 



I A SWITCH/IOCB CAN BE THOUGHT OF AS A STRUCTURE CONTAINING TRANSFER 
VECTORS 



YOU ARE NOW READY FOR WORKSHOP 
#5 
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TOPIC VIII 
The iox Multics Subroutine 
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Topic VIII THE IOX_ SUBROUTINE Topic VIII 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 

1. Open and close I/O switches usins iox_. 

2. Read data from the user's terminal. 

3. Display information on the user's terminal. 

4. Read and write stream files. 

5. Read and write sequential and keyed files. 
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INTRODUCTION TO USING iox 



• WHY USE iox_ RATHER THAN PL/I I/O STATEMENTS? 

iox_ IS MORE EFFICIENT 

I WRITTEN IN aim 

D NUMBER OF MEMORY ACCESSES 
1 iox_ ACCESSES 'IOCB» ONLY 
I PL/I STATEMENTS ACCESS 'FSB' (FILE STATE BLOCK) AND 'IQCB' 

D MORE POWERFUL 

I BETTER ERROR DETECTION 

1 ACCEPTED CONVENTION FOR SYSTEM CODE 



# WARNING: SHOULD NOT MIX iox AND PL/I I/O DUE TO INCONSISTENCIES 
(DIRECT CALLS TO iox DO NOT "MAINTAIN 'FSB') 
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iox OPENING MODES 



• iox OPENING MODES SUPPORTED AND THE iox OPERATIONS PERMITTED FOR 
EACl OPENING: 



NO 



NAME 



I/O OPERATIONS PERMITTED 



1 stream__input 

2 streanPoutput 

3 stream_input__ output 

4 sequential_input 

5 sequential__output 

6 s equential~input — output 

7 sequential_update 

8 keyed_sequential__input 

9 keyed_sequential__output 

10 keyed_sequential_update 

11 direct__input 

12 direct~output 
1 3 . direct""update 



get_line, get_chars, position 
put~chars 

I + 2 

read_record, read_length, position 

write record 

4 + 5" 

4, rewrite__record , delete_record 

read_record , read__length, position, 

~"seek_key, re"ad_key 
seek_key,~"write_record 
8 + 9 , rewrite__record ,delete_record 

read__record , read_length, seek_key 
seek_key, write_record "** 

I I +"~1 2,rewrite — record ,delete_record 



SEE >ldd>include>iox_modes.incl.p!1 



• NOTE : 



I THE 'open' , ' close 1 , 'control' , AND 'modes' OPERATIONS ARE PERMITTED 
WITH ANY OPENING MODE 



1 THE ABOVE NUMBERS ARE USED IN CALLS TO iox TO SPECIFY OPENING 
MODES 



I THE LONG NAME (AS GIVEN ABOVE) IS USED WITH ' io call' 



PL/I SPECIFIES THE OPENING MODE IN THE FILE DESCRIPTION 
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STANDARD SWITCH ATTACHMENTS 
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STANDARD SWITCH ATTACHMENTS 



THE MULTICS STANDARD PROGRAMMING ENVIRONMENT MAKES USE OF FOUR SWITCHES 
WHICH ARE ATTACHED AND OPENED AS PART OF THE PROCESS CREATION CYCLE 



• THE STANDARD ATTACHMENTS ARE: 



user_i/o tty__ -login__channel 

**" stream_input_output ~" 

user — input syn__ user_i/o 

user~output • syn_ user_i/o "~ 
error_output "" syn__ user_i/o 



• IN TERMS OF iox , THESE SWITCHES ARE IDENTIFIED BY THE FOLLOWING 
DECLARATIONS: 



I del iox__$user_io external pointer; 

I del iox^use^input external pointer; 

I del iox — $user_output external pointer; 

del iox_ $error_output external pointer; 

II EXAMPLE 

call iox_$put_ > chars ( iox_$user_output , buffer_ptr, 
"~ buffer_length, code); 
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iox ENTRY POINTS 



# THERE ARE OVER 25 ENTRY POINTS FOR THE iox SUBROUTINE (SEVERAL ARE 
PRESENTED IN THE REMAINDER OF THIS TOPIC) " 



• THE FIRST 7 ENTRY POINTS: 



I ARE SUMMARIZED ON THE NEXT 2 PAGES 



I WILL BE STUDIED IN DETAIL BY REFERRING TO THE SUBROUTINES MANUAL 



1 WILL BE USED IN WORKSHOP 6 



I REPRESENT SOME COMMONLY USED ENTRY POINTS THAT WOULD BE USED TO 
PROMPT A USER FOR A KEY AND THEN FIND THE CORRESPONDING RECORD 
IN A KEYED FILE 



THE OTHER ENTRY POINTS (STARTING ON PAGE 8-7) WILL BE COVERED IN 
MUCH LESS DETAIL 



• SEVERAL OPERATIONS INVOLVE THE USE OF A BUFFER 



Q A BUFFER IS A BLOCK OF STORAGE PROVIDED BY THE CALLER OF THE 
OPERATION AS THE TARGET FOR INPUT OR THE SOURCE FOR OUTPUT 



I A PTR TO THE BUFFER IS PASSED TO iox SUBROUTINES 
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iox ENTRY POINTS 

• iox_$attach__name 

ACCEPTS A SWITCHNAME 

1 RETURNS A POINTER TO THE 'IOCB' FOR THE CORRESPONDING SWITCH 

1 DMCRIPTIO™ SWITCH M ACC0RDANCE W ITH THE SUPPLIED ATTACH 



iox_$open 

OPENING MODE IS SPECIFIED BY A NUMBER (SEE PAGE 8-2 



• iox_$get_line 

THE NEWLINE CHARACTER SIGNIFIES THE END OF THE LINE 

1 A CODE OF ZERO IS RETURNED ONLY IF A NEWLINE CHARACTER IS READ 
I THE NEWLINE ITSELF IS READ INTO THE BUFFER 
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iox ENTRY POINTS 



• iox__$seek_key 



THE NEXT RECORD POSITION AND CURRENT RECORD POSITION ARE SET TO 
THE RECORD WITH THE GIVEN KEY 



I USED BEFORE DOING A read, delete, rewrite, ETC. 



'• iox $read record 



READS THE NEXT RECORD IN A STRUCTURED FILE 



I KEYED READS FIRST REQUIRE A CALL TO iox_$seek_key 



# iox $close 



iox_$detach_iocb 

4 

D DOES NOT FREE THE IOCB'S STORAGE 
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iox ENTRY POINTS 



• THE REST OF THIS TOPIC WILL SERVE AS AN OVERVIEW OF OTHER iox 
ENTRY POINTS 



iox_$ attach_ptr 

Q call iOx_$attach_ptr ( iocb_ptr , atd , ref_ptr, code); 



BEHAVES LIKE iox $ attach name, EXCEPT iocb ptr IS AN INPUT NOT 
AN OUTPUT VARIABLE 



iox $find iocb 



Q call iox_$find__iocb ( swi tc hn am e , iocb ptr, code); 



I GIVEN A SWITCHNAME, RETURNS A POINTER TO THE IOCB, BUT DOES NO 
ATTACHMENT (IF THE BLOCK DOES NOT ALREADY EXIST, IT IS CREATED) 



D iox_$ find__iocb + iox_$attach_ptr = iox_$attach_name 



• iox $look iocb 



call iox_$look_iocb (switchname, iocb_ptr, code); 



I BEHAVES LIKE iox_$find iocb, HOWEVER DOES NOT CREATE A BLOCK IF 
ONE DOES NOT ALRfADY EXIST 
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iop ENTRY POINTS 

iox_$move__attach 

Q call iox_$move_attach (iocb_ptr1, iocb ptr2, code); 

I INCLUDED FOR COMPLETENESS (NOT FOR NOVICE USERS) 



MOVES AN ATTACHMENT FROM ONE ATTACHED SWITCH TO ANOTHER DETACHED 
SWITCH 



I THE PERFECT EXAMPLE (FOR WHICH move_attach WAS WRITTEN) IS THE 
CASE OF file_output, IN WHICH A TEMPORARY SWITCH IS CREATED, THE 
CURRENT ATTACHMENT OF user_output IS MOVED TO THAT TEMPORARY 
SWITCH, AND THEN user_output IS ATTACHED TO THE OUTPUT FILE 



iox_$ destroy__iocb 

Q call iox_$destroy_iocb ( iocb_ptr , code); 

I FREES THE STORAGE USED BY A DETACHED CONTROL BLOCK 
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iox ENTRY POINTS 

• iox_$get_chars 

D call iox_$get_chars (iocb_ptr, buff_ptr, n, n_read , code); 



I USER REQUESTS n BYTES (CHARACTERS) FROM A STREAM FILE OR DEVICE 
(ACTUALLY NUMBER READ IS n read BYTES) 



IF n = n read THEN code = 



I IF n read < n THEN code = error table $ short record 



D IF NEXT BYTE IS "END OF FILE" THEN code = error_table_$end of info 
(NOTE THAT THE 'end file 1 CONDITION IS NOT SIGNALLED WHEN USING 
iox ) _ . 



Q READS NEWLINE CHARACTERS INTO BUFFER JUST LIKE ANY OTHER CHARACTER 



I IF n IS GREATER THAN THE SIZE OF THE RECEIVING BUFFER, OVERFLOW 
CHARACTERS WILL BE WRITTEN PAST THE END OF THE BUFFER, YIELDING 
POTENTIALLY DISASTROUS RESULTS 



I BUFFER OUGHT TO BE EXPLICITLY FLUSHED PRIOR TO CALL, BECAUSE 
JUST n_read CHARACTERS WILL BE OVERWRITTEN 

i ALTERNATIVE: 

del max_buff char (80) based (buff_ptr); 
del buff char (n_read) based (buff_ptr); 



Not To Be Reproduced 8-10 F15C 



iox ENTRY POINTS 



iox $put chars 



D call iox__ $put_chars ( iocb__ptr , buff_ptr, n, code); 



I WRITES n BYTES (CHARACTERS) TO THE UNSTRUCTURED FILE OR DEVICE 



I BUFFER SHOULD CONTAIN A NEWLINE, IF ONE IS INTENDED (THERE IS NO 
«put_line' ENTRY POINT) 



D IF OPEN FOR stream_output THE CHARACTERS ARE APPENDED TO THE END 
OF THE FILE. IF OPEN FOR stream_input_output FILE TRUNCATION 
OCCURS JUST BEFORE THE NEXT BYTE 



iox $write record 



call iox_$write_record ( iocb_ptr , buff_ptr, rec_len, code); 



I ADDS A RECORD TO A STRUCTURED FILE 



I IF OPEN FOR sequential_output, THE RECORD IS APPENDED TO THE 
FILE. IF OPEN FOR sequent! al_in put output, FILE TRUNCATION OCCURS 
JUST BEFORE THE NEXT RECORD 



I iox $seek key MUST BE CALLED BEFORE DOING A KEYED WRITE IN ORDER 
TO "SET THE KEY" FOR INSERTION 
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iox ENTRY POINTS 



iox $rewrite record 



D call iox__ $rewrite__record ( iocb__ptr , buff_ptr, rec__len, code); 



I REPLACES THE CURRENT RECORD IN A STRUCTURED FILE THAT HAS BEEN 
OPENED FOR "UPDATE" 



fl IF THE CURRENT RECORD POSITION IS NULL, error table $no record 
IS RETURNED 



I THUS IT IS FIRST NECESSARY TO "LOCATE" THE RECORD TO BE REPLACED 
(USING read_record , seek_key OR position ENTRY POINTS) 



• iox_$read_length 

D call iox^read^length ( iocb_ptr , rec_len, code); 

1 RETURNS THE LENGTH OF THE NEXT RECORD IN A STRUCTURED FILE 



I IF THE NEXT RECORD POSITION IS AT THE END OF FILE, code 
error table $end of info 



B APPLICATION: TO DETERMINE HOW LONG THE BUFFER MUST BE IN ORDER 
TO HOLD THE NEXT RECORD TO BE READ (EXAMPLE: VARIABLE LENGTH 
RECORDS) 
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iox ENTRY POINTS 



iox $delete record 



D call iox_$delete_record C iocb_ptr , code); 



1 DELETES THE CURRENT RECORD FROM THE STRUCTURED FILE, WHOSE SWITCH 
MUST BE OPENED FOR "UPDATE" 



fl IF THE CURRENT RECORD IS NULL, code s error__table_$no_record 



AGAIN, IT IS FIRST NECESSARY TO "LOCATE" THE RECORD TO BE DELETED 
(USING read_record, seek_key OR position ENTRY POINTS) 



• iox $read key 



call iox_$read__key (iocb_ptr, key, rec__len, code); 



I RETURNS BOTH THE KEY AND THE LENGTH OF THE NEXT RECORD IN AN 
INDEXED FILE 



I code = error table $end_of info IF THE NEXT RECORD POSITION IS 
AT THE END OF" FILE" 



I code = error table_$no_record IF THE NEXT RECORD POSITION IS 
NULL 
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iox ENTRY POINTS 

iox_$ position 

Q call iox_ $ position (iocb_ptr, type, n, code); 

I POSITIONS TO THE BEGINNING OR END OF A FILE, OR SKIPS FORWARD OR 
BACKWARD OVER A SPECIFIED NUMBER OF LINES OR CHARACTERS 
(UNSTRUCTURED FILES) OR RECORDS (STRUCTURED FILES) 

type IDENTIFIES THE TYPE OF POSITIONING (INPUT) 
-1 GO TO THE BEGINNING OF FILE (n = 0) 
+1 GO TO THE END OF FILE (n = 0) 

Q SKIP NEWLINE CHARACTERS OR RECORDS (n positive or negative) 
2 POSITION TO AN ABSOLUTE CHARACTER OR RECORD (n) 
3 SKIP CHARACTERS ( stream_input) (n positive or negative) 
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iox ENTRY POINTS 



iox $modes 



I USED TO OBTAIN OR SET MODES THAT AFFECT THE SUBSEQUENT BEHAVIOR 
OF THE SWITCH (BEST KNOWN MODES ARE THOSE ASSOCIATED WITH tty_ : 
echoplex , tabs, polite , etc .) 



call iox__$modes (iocb_ptr, new_modes, old_modes, code); 



I SWITCH MUST BE ATTACHED VIA AN I/O MODULE THAT SUPPORTS MODES 
(EXAMPLE: tty_ SUPPORTS MODES, vfile_ DOES NOT) 



FOR A LIST OF THE VALID MODES, SEE THE DESCRIPTION OF THE MODULE 
INVOLVED 



# iox * control 



call iox_$control ( iocb__ ptr , order, info_ ptr , code); 

I info ptr IS NULL OR POINTS TO DATA WHOSE FORM DEPENDS ON THE 
MODULE 



I PERFORMS A SPECIFIED CONTROL ORDER ON AN I/O SWITCH; THE ALLOWED 
ORDERS DEPEND ON THE I/O MODULE VIA WHICH THE SWITCH IS ATTACHED 
(REFER TO THE I/O MODULE WRITE UPS) 

D EXAMPLES OF tty_ CONTROL ORDERS: set delay, set editing chars, 
quit — enable, hangup 

EXAMPLE OF vfile CONTROL ORDER: read position (RETURNS THE 
ORDINAL POSITION - (0, 1, 2...) OF THE" NEXT RECORD/BYTE AND 
THE END OF THE FILE) 
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AN EXAMPLE USING iox 



pri.nt__fj.le: proc; 

del iox $ attach name entry (char (*) , ptr , char (*), ptr , fixed bin (35)); 

del iox~$ detach iocb entry (ptr, fixed bin (35)); 

del iox~"$open entry (ptr, fixed bin, bit (1) unaligned, fixed bin (35)); 

del iox~"$ close entry (ptr, fixed bin (35)); 

del iox~$put chars entry (ptr, ptr, fixed bin (21), fixed bin (35)); 

del iox~$read* record entry (ptr, ptr, fixed bin (21), fixed bin (21), 

fixed bin (35)); 

del iox $read_length entry (ptr, fixed bin (21), fixed bin (35)); 

del iox"$get line entry (ptr, ptr, fixed bin (21), fixed bin (21), 

fixed bin (35)); * 

del iox_$control entry (ptr, char (*) , ptr, fixed bin (35)); 

del iox $user_output ext ptr; 

del ioc5 ptr ptr init (null ()); 

del code"~fixed bin (35) init (0); 

del com err entry options (variable); 

del ME char"(10) static init ( "print_file") options (constant); 

del LF char (1) static options (constant) init (" 

">; 

del 1 info, 

2 next position fixed bin (34), 

2 last~position fixed bin (34); 
del buffer char (buf_len) based (buf_ptr); 
del Duf_len fixed bin (21); - 
del ouf ptr ptr init ( nullO ); 
del rec__len fixed bin (21); 
del l fixed bin; 
del (null, addr) builtin; 
del cleanup condition; 

on cleanup call WRAPUP; 

call iox $attach name ("sw", iocb_ptr , "vfile_ sample_file" , null (), code); 
if code "*■= "" 
then call WRAPUP; 

call iox $open ( ioeb_ptr , 4, "0 w b, code); 
if code "% 
then call WRAPUP; 

call iox_$control ( iocb__ptr , "read_position n , addr(info), code); 
if code ~= 
then call WRAPUP; 

call iox $read_length ( iocb_ptr , rec_len, code); 
if code "*= ~ 

then call WRAPUP; 

buf len s rec len + 40; 
allocate buffer set (buf ptr); 
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AN EXAMPLE USING iox 



do i = 1 to last position; , 

call iox $reacT record (iocjs^ptr, buf^ptf , buf len , rec^-l€h, c$d-e7; 

if code *a " -"^ -""^ 

then call WRAPUP; 

substr (buffer, rec_len+1 , 1 ) = LF ; 

call iox $put_chars~"( iox_$user__output , buf_ptr, rec_len + 1, code); 

if code "*= "" 

then call WRAPUP; 
end /* do i */; 

call WRAPUP; 

W RA^£U_g : proc; 

if code *s 

then call com_err_ (code, ME); 

if iocb^ptr *= null () 
then do; 

call iox_$close ( iocb_ptr , code); 

call iox_$detach_iocb ( iocb_ptr , code); 
end /* then do */; 

if buf_ptr *s null () 

then free buf_ptr -> buffer ; 

goto FINIS; 

end /* WRAPUP */; 

FINIS: 

end /* print_file */; 

r 14:40 0.259 32 

! vfs sample_file 
type: sequential 
records: 5 
r 14:41 0.261 19 

! print_file 

This Ts record number 1 
THIS IS RECORD TWO 
Hi, I'm the third record 
Would you believe four? 
I am the last record 
r 14:41 0.288 7 
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Topic IX THE IOA_ SUBROUTINE Topic IX 



OBJECTIVES: 



Upon completion of this topic, students should be able to: 



1. Write simple character strinss to the user's terminal 



2. Use iteration and conditional evaluation to form complex 
output strinss for display on the terminal. 



3. Write to a file via an I/O switch. 

4. Write to a file using the liultics Virtual Memory. 
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CHARACTERISTICS 



• USED FOR FORMATTING A CHARACTER STRING FROM FIXED-POINT NUMBERS, 
FLOATING-POINT NUMBERS, CHARACTER STRINGS, BIT STRINGS, AND POINTERS 



I THE CHARACTER STRING IS FORMATTED ACCORDING TO THE CONTROL 
CHARACTERS EMBEDDED IN AN 'ioa ' CONTROL STRING 



I THE ENTIRE PROCEDURE IS SIMILAR TO FORMATTING OUTPUT IN PL/I OR 
FORTRAN 



• SEVERAL ENTRY POINTS ARE PROVIDED IN « ioa ' TO PROVIDE VARIOUS OPTIONS 



I SINCE ALL OF THE ENTRY POINTS CAN BE CALLED WITH A VARIABLE 
NUMBER OF ARGUMENTS, THEY ALL MUST BE DECLARED 'entry 
optionsC variable) • 



' ioa_« NORMALLY APPENDS A NEWLINE CHARACTER TO THE END OF THE 
STRING CREATED 



I A CORRESPONDING ENTRY POINT IS PROVIDED FOR EVERY STANDARD ENTRY 
POINT WHICH SPECIFIES THAT "NO NEWLINE" IS TO BE APPENDED 
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ENTRY POINTS 

• ENTRY POINTS IN ioa_ ARE: 

I ioa__ , toa_$nnl 

Q call ioa__ (control_string , argj_, ..., argN); 

I FORMAT THE INPUT DATA ACCORDING TO THE CONTROL STRING, AND 
WRITE THE RESULTING STRING ON »user_output' 



Q ioa_$ioa_stream, ioa__$ioa_ stream nnl 

Q call ioa_$ioa_ stream (switchname, control_string , argl , ..., 
"" arg N) ; "" 

D FORMAT THE RESULTING STRING AS ABOVE, BUT THE STRING IS THEN 
WRITTEN TO AN I/O SWITCH SPECIFIED BY THE SWITCHNAME ARGUMENT 



I ioa_$ioa__ switch, ioa_$ioa__switch_nnl 

D call ioa_$ioa_switch ( iocb ptr , control string, argl , ..., 

argNT; ~ 

I IDENTICAL TO THE ioa $ioa_stream AND ioa $ioa $ stream nnl ENTRY 
POINTS EXCEPT THAT "t HE I/O SWITCH IS DESIGNATED BY~A POINTER 
TO ITS IOCB, RATHER THAN BY SWITCHNAME (HENCE, THESE ENTRY 
POINTS ARE A BIT MORE EFFICIENT^ 
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ENTRY POINTS 



ioa — $rs, ioa_$rsnnl 

| call ioa $rs ( eon tro lustring , ret_string, ret_length, arg1_, 
"" . . . , arg N) ; 

I EDITING OCCURS AS IN THE ABOVE CALLS, BUT INSTEAD OF BEING 
WRITTEM TO AN I/O SWITCH, THE STRING IS PASSED BACK TO THE 
CALLER IN A CHARACTER STRING VARIABLE 

I THE CHARACTER STRING VARIABLE PROVIDED BY THE CALLER MAY BE 
VARYING OR NONVARYING, ALIGNED OR UNALIGNED AND OF ANY LENGTH 

I THE LENGTH OF THE CREATED STRING IS ALSO RETURNED 



1 ioa_$rsnp, ioa_$rsnpnnl 

n THESE ARE IDENTICAL TO THE ioa $rs AND ioa_$rsnnl ENTRY POINTS 
EXCEPT THAT THEY DO "NO PADDING" OF A STRING RETURNED INTO A 
NONVARYING CHARACTER STRING 
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CONTROL STRING 



• A NON-VARYING CHARACTER STRING CONSISTING OF TEXT TO BE COPIED AND/OR 
ioa CONTROL CODES 



ioa_ CONTROL CODES ARE ALWAYS IDENTIFIED BY A LEADING CIRCUMFLEX 
(*) CHARACTER, AND SPECIFY THE TYPE OF EDITING TO BE DONE FOR THEIR 
CORRESPONDING argi 



• PROCESSING BY ioa BEGINS BY SCANNING THE CONTROL STRING UNTIL A 
CIRCUMFLEX IS FOUND, OR THE END OF THE STRING IS REACHED 



I ANY TEXT (INCLUDING BUNKS) PASSED OVER IS COPIED TO THE OUTPUT 
STRING 



I CONTROL CODES ARE INTERPRETED, GENERALLY BY EDITING THE NEXT 
argi INTO THE OUTPUT STRING IN A FASHION DICTATED BY THE CONTROL 
CODE 
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CONTROL STRING 



CONTROL CODE ACTION 



"d 


"nd 


~i 


*ni 


*f 


*nf 
*n.df 



ne 






"no 


w 


~nw 


a 


*na 


b 


*nb 

*n.db 

*Tdb 



— 


n- 




X 


*n A 




S 


~ns 




( 


A n( 




) 






[ 






■] 






t 






'nt 


*n.m 


t 



Edit a fixed-point decimal integer 

same as *d (FOR COMPATIBILITY WITH FORTRAN) 

Edit a floating-point number 

Edit a floating-point number in exponential 
form 

Edit a fixed-point number in octal 

Edit a full machine word in octal 

Edit a character string in ASCII 

Edit a bit string 



Edit a pointer 
n | Insert formfeed character(s) 

n / Insert newline character(s) 

Insert horizontal tab character(s) 

Insert space character(s) 

Insert circumflex character(s) 

Skip argument(s) 

Start an iteration loop 

End an iteration loop 

Start an if/then/ else or case selection group 

Limit the scope of a *[ 

Use as a clause delimiter between "[ *] 

Insert enough space to reach column n 
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CONTROL STRING 



• 



WHEN n AND/OR d APPEAR IN A CONTROL CODE, THEY GENERALLY REFER TO A 

?S L SnJS?, H ,°J A REPETITI0N FACTOR (THE EXACT MEANING DEPENDS ON 
THE CONTROL CODE WITH WHICH THEY APPEAR) 



™ E 4 0R i MUST BE SPECIFIED AS UNSIGNED DECIMAL INTEGERS, OR AS 
THE T-ETTgR «v» , IN WHICH CASE, THE NEXT argi ARGUMENT (WHICH 
MUST BE FIXED BINARY) IS USED TO OBTAIN THE ACfUAL VALUE 



llmli^i ^WSSS? ' i0a - USES A mLD LARGE EN0UGH T0 



• 



SJ&^pSpSStf^JLP SPECIF ^» ioa_ IGNORES THE WIDTH AND 



SELECTS AN APPROPRIATE WIDTH 



• 



NUMERIC CONTROL CODES TAKE ANY PL/I NUMERIC DATA TYPE, TNCLUDING A 
NUMERIC CHARACTER STRING, AND USE STANDARD PL/I CONVERSION ROUTINES 
IF NECESSARY 



• ARGUMENTS THAT ARE EDITED INTO THE CONTROL STRING MAY BE ARRAYS 
I THE ELEMENTS ARE TREATED SEPARATELY IN ROW MAJOR ORDER 
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CONTROL STRING 



THE FOLLOWING EXAMPLES ILLUSTRATE MANY, BUT NOT ALL, OF THE FEATURES 
OF THE ioa SUBROUTINE. THE SYMBOL B IS USED TO REPRESENT A SPACE 
IN THE PLACES WHERE THE SPACE IS SIGNIFICANT 

Source: call ioa_("This is "a the third of ~a» ,"Mon" , H July") ; 
Result: This is Mon the third of July 

Source: call ioa_("date "d/*d/"d, time *d:*d" ,6,20,74,2014, 36); 
Result: date 6/20/74, time 2014:36 

Source: call ioa_( "overflow at ~p",ptr); 
Result: overflow at 271 14671 

Source: call ioa_( "~2 (*2 (*w ") V") " ,w1 ,w2,w3,w4) ; 

Result: 112233445566 000033004400 
000000000001 777777777777 



Source: bit="1 101 1 100001 1 "o; 

call ioa_( I, *vxocts A .3b hex=* .4b" ,6, bit ,bit) ; 

Result: b£b££boct=67031Shex=DC3 

Source: call ioa_("~f "e *f "5 .2f" , 1 .0, 1 , 1e-1 0, 1 ) ; 
Result: 1. ISl.eO B1.e-10 B1.00 

Source: call ioa_("*(*d ")" ,1 ,2,56, 198, 456.7, 3e6); 
Result: 1 2 56 1 98 456 3000000 

Source: abs sw=0; 

call ioa $rsnnl( "*v( Absentee user *)*a "a logged out.", 

"" out_str,out_cnt,abs_sw,"LeValley" ,"Shop") ; 

Result: out cnts25; 

out""strs"Le Valley Shop logged out." 
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CONTROL STRING 



Source: abs swsl; /* Using same call to ioa $rsnnl */ 

call ioa_$rsnnl("*v( Absentee user *T*a "a logged out.", 

~ out_ > str,out_cnt,abs_sw,"Le Valley" ."Shop") 

Result: out — cnt=39; 

out~str= "Absentee user Le Valley Shop logged out." 

Source: del a(2,2)fixed bin init(1 ,2,3,4); 
call ioa_("~d*s ~d ~w",a); 

Result: 1 3 000000000004 

Source: del b(6:9)fixed bin init(6,7,8,9); 
call ioa_("~v( A 3d~)",dim(b,1),b); 

Result: 6 7 8 9 

Source: sw="0"b; 

call ioa_ ("a= A d *[b=~d~; "a"] c=*d" ,5,sw,7, 9) ; 

Result: a=5 c=9 

Source: sw= "1 "b; 

call ioa_ ("asM -[bs"d*; ~s~] c=*d" ,5,sw,7,9); 

Result: as5 b=7 c=9 

Source: dirs">"; ename="foo"; 

call ioa ("Error in segment A a*[>*]*a", dir, 
(dir *=">") , ename); 

Result: Error in segment >foo 

Source: dir=">foo"; ename="bar"; 

call ioa_ ("Error in segment *a~[>*] *a" , dir, 
(dir * = ">») , ename) ; 

Result: Error in segment >foo>bar 

Source: option=2; /* Assume following call.is on one line */ 
call ioa__ ("Insurance option selected: 
*[no fault"; bodily injury~;propertydamage~] " , option); 

Re Sill t". ; Tn <!iiranffo n n* inn sal a<-> +■ aA . Kn>4 4 1 u 4 » -i <i« <• 
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CONTROL STRING 



YOU ARE NOW READY FOR WORKSHOP 
#6 
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Topic X MULTICS STORAGE SYSTEM SUBROUTINES Topic X 

OBJECTIVES! 

Upon completion of this topic* students should he able to: 



1. Add and remove entries to and from the Multics Storage 
System. 



2. Manipulate pathnames using Multics subroutines. 

3. Obtain status information on entries in the storage system. 



4. Change the access control lists (ACLs) of various entries in 
the storage system. 



5. Use Multics subroutines to obtain information about a user's 
homer working* and process directories. 



6. Discuss the access required to perform any of the above 
operations. 
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THE MULTICS STORAGE SYSTEM 



THE STORAGE HIERARCHY IS ORGANIZED INTO AN INVERTED TREE STRUCTURE 



I THIS TREE IS MADE UP OF DIRECTORY SEGMENTS, SEGMENTS, MULTI-SEGMENT 
FILES AND LINKS 



• FOR NON-DIRECTORY SEGMENTS: 



I SUBJECT TO THE THREE ACCESS CONTROL MECHANISMS, THE USER IS FREE 
TO CREATE, DESTROY, AND MODIFY THE CONTENTS OF SEGMENTS 



1 USER-CREATED SEGMENTS NORMALLY "RESIDE" IN THE RING OF THE CREATOR. 
THE USER IS FREE TO ACCESS SUCH SEGMENTS WITHOUT HAVING TO "CROSS" 
ANY RING BOUNDARIES 



FOR DIRECTORY SEGMENTS: 



1 THE USER MAY CREATE, DESTROY, AND MODIFY DIRECTORY SEGMENTS, BUT 
NOT DIRECTLY (THEY ARE PROTECTED AGAINST DIRECT ACCESS VIA THE 
RING MECHANISM) 



D ALLOWING USERS TO MANIPULATE DIRECTORY SEGMENTS DIRECTLY WOULD 
BE INVITING CHAOS, SINCE DIRECTORY SEGMENTS DETERMINE THE INTEGRITY, 
SECURITY AND CONSISTENCY OF THE HIERARCHY 



1 DIRECTORY SEGMENTS ARE PLACED IN RING AND USERS ULTIMATELY 
ACCESS SUCH SEGMENTS BY USING A SYSTEM-PROVIDED GATE PROCEDURE 
CALLED hcs 
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THE MULTICS STORAGE SYSTEM 



• THE hcs SUBROUTINE 



I PROVIDES VARIOUS ENTRY POINTS FOR MANIPULATION OF THE STORAGE 
SYSTEM AND VIRTUAL ADDRESS SPACE 



I ALL ACCESS TO THE STORAGE SYSTEM IS ACCOMPLISHED VIA THIS GATE 
PROCEDURE 



THE STORAGE MANIPULATION SUBROUTINES COVERED IN THIS COURSE ARE 
SUMMARIZED BELOW: 
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SUMMARY OF DISCUSSED SUBROUTINES 



CREATING STORAGE SYSTEM ENTITIES 

hes__$ append__branch 
hcs~$ append~branehx 
he s~$ append~lin k 
hcs_$create~branch_ 
he s~$ make_seg 

DELETING STORAGE SYSTEM ENTITIES 

delete_$path 
delete~$ptr 

OBTAINING STATUS INFORMATION 

hcs_$status_ 
he s~$ status_long 
he s__$ sta tus~min f 
he s~$ status_mins 

SECURITY 

get^group^id^ 

get_gro up~id~$ tag_star 

he s~$ ad d_ac 1_ en t r i e s 

hcs3add~dir_acl_entries 

he s_$ del ete — acl__en tries 

he s~$ del ete~dir_acl__en tries 

hcs~$fs_get~mode ~~ 

hcs~$list_acl 

hcs~$list~dir_acl 

he s_$ r e pile e_ac 1 

hcs_$replace__dir — acl 

WORKING, DEFAULT, AND PROCESS DIRECTORIES 

change__default — wdir_ 
chang e~wdir_ "" ~* 
get_def aul t~wd ir_ 
get~pdir_ " "~ 
get__ wdir" 
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SUMMARY OF DISCUSSED SUBROUTINES 



MANIPULATING PATHNAMES 

ab sol ut e — pa thn ame_ 

ab sol ute~pathname~$ add__ suf f ix 

expand_pathname_ ""* ~" 

expand~pathname_$add_suff ix 

ex pand~ pa thn am e_$ component 

expand__pathname_$component_add__ suffix 

get_shortest_path_ 

pathname_ "" """ 

pa thn am e~$ com po n en t 

pathname^ com ponent_ check 

NAMING AND MOVING DIRECTORY ENTRIES 

he s__$ chname_f il e 
he s_$ chname_seg 
he s~$ f s_mov e_ f i 1 e 
he s~$ f s~mov e_seg 

AFFECTING LENGTH OF ENTRIES 

ad j us t_bi t_co un t__ 
he s__$ set_bc 
hcs_$truncate — file 
terminate_fil"e_ 

MANIPULATING THE ADDRESS AND NAME SPACES 

hcs_$ fs — get_path_name 
he s~$ fs~get~ref_name 
hcs_$ fs__get~seg~ptr 
he s~$ m a ke_ se g "~ 
initiate "file_ 
term_$ re"Fn am e 
term~$seg — ptr 
term~$ sing le_ref name 
term_$term_ ~" 
term^unsnap 
terminate file 
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CREATING STORAGE SYSTEM ENTITIES 



This Page Intentionally Left Blank 
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CREATING STORAGE SYSTEM ENTITIES 



Requires append permission 
Can use to create segments 




Gives full access to *.Sys Daemon. # 



Obeys initial ad 



Can set access for one user_id 



Can specify the user_id 



Can use to create directories 
Can set ring brackets 
Can set copy switch 



Can set bit count 



Can be told to chase links 
Can move quota to directory 



Can manipulate aim 



Requires info structure 
Initiates created segment 



_X_ 
X 



X 
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CREATING STORAGE SYSTEM ENTITIES 



# call hcs_$make_seg (dir_name, entryname, ref__name, mode, 

seg_ptr , code) ; 



• call hcs_$append_branch (dir_name, entryname, mode, code); 



/ 'J 

• call hcs_$append__branchx (dir__name, entryname, mode," fern/g^ ^^M*-** i 

""ue*p^id=f-crir_sw, <copy_sw, bit_count, code); 
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CREATING STORAGE SYSTEM ENTITIES 



• call hcs__$create_branch_ (dir_name, entryname, info_ptr , code); 



D info_ptr POINTS TO THE FOLLOWING STRUCTURE: 

/* BEGIN INCLUDE FILE create_branch__info .incl .pl1 

- - - created January 1975 */ 

/* this include files gives the argument structure for 
create_branch__ */ 

del 1 create_branch_info aligned based, 
2 versTon fixed bin, 

/* set this to the largest value given below */ 
2 switches unaligned, 

3 dir sw bit (1) unaligned, 

/"* if on, a directory branch is wanted */ 
3 copy_sw bit (1) unaligned, 

/* if on, initiating segment will be done by copying */ 
3 chase_sw bit (1) unaligned, 

/* Tf on, if pathname is a link, it will be chased */ 
3 priv upgrade sw bit (1) unaligned, 

/♦""privileged creation (ring 1) of upgraded object */ 
3 parent ac_sw bit (1) unaligned, 

/* iT on, use parent's access class for seg or 
dir created */ 
3 mbzl bit (3D unaligned, 
/* pad to full word */ 
2 mode bit (3) unaligned, 

/* segment or directory for acl for userid */ 
2 mbz2 bit (33) unaligned, 
/* pad to full word */ 
2 rings (3) fixed bin (3), 

/* branch's ring brackets */ 
2 userid char (32) , 

/* user's access control name */ 
2 bitcnt fixed bin (24), 

/* bit count of the segment */ 
2 quota fixed bin (18), 

/* for directories, this am't of quota will be moved 
to it »/ 
2 accessed ass bit (72); 

/* is the access class of the body of the branch */ 

/* The following versions are implemented . . . */ 
/* (Changes to structure require defining new static 
initialized variable) */ 

del create branch_version_1 static fixed bin init (1); 

/* branch info valid through access class field */ 

/ 1ft fJMT% T%.lf%Ttl»>I7 r?TTt? .*« **. *+ 4m ^ Wm« «•%%* *« t* n vt #r+ -i w* y* 1 r> 1 1 _ _ ^k / 

/ " CHu XlilLlli't r Xi-H — — — Qt 6dUc ui auwu awaw «xw\.j. t px i — - — / 
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CREATING STORAGE SYSTEM ENTITIES 



* NOTES: 



II FOR BOTH hcs__$make_seg AND hcs_$append_branch: 
B THE BIT COUNT AND COPY SWITCH ARE SET TO 
THE SPECIFIED MODE IS SET FOR Person_id .Project_id .* 



FOR hcs_$make_seg , hcs_$append_branch AND hcs_$append_branchx TH 
MODE IS SPECIFIED AS FOLLOWS: *" 



I FOR SEGMENTS: 



read the 8-bit is 1 (01000b) 

execute the 4-bit is 1 (00100b) 
write the 2-bit is 1 (00010b) 



B FOR DIRECTORIES: 

status the 8-bit is 1 (01000b) 

modify the 2-bit is 1 (00010b) 

append the 1-bit is 1 (00001b) 



THE MODE FOR hcs $create branch IS SPECIFIED IN SIMILAR MANNER, 
USING ONLY 3 BIT'S 
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CREATING STORAGE SYSTEM ENTITIES 



/* BEGIN INCLUDE FILE 



access mode values. incl .pl1 



*/ 



Values for the "access mode" argument so often used in hardcore 

James R. Davis 26 Jan 81 MCR 4844 

Added constants for SM access 4/28/82 Jay Pattin 



del 



del 



CN ACCESS 


init ( 


n 000"b) , 


R~ACCESS 


init i 


"100 n b) , 


E~ACCESS 


init i 


"010"b) , 


tTACCESS 


init ( 


"001 "b) , 


RE ACCESS 


init ( 


."110"b) , 


REff ACCESS 


init < 


:"111"b) , 


RW_ACCESS 


init ( 


: n 101"b) , 


S ACCESS 


init ( 


."lOCb) , 


M~ACCESS 


init ( 


."OlCb) , 


A""ACCESS 


init ( 


. M 001"b) , 


SA ACCESS 


init ( 


:"101"b) , 


SM ACCESS 


init ( 


. n 110"b) , 


SMA ACCESS 


init ( 


:"111"b)) 


t (37 internal static 


options 


( constant) ; 


(N ACCESS BIN 


init ( 


lOOOOOb) , 


R'ACCESS BIN 


init 


:01000b) , 


e~access""bin 


init 


:00100b) , 


vTaccess~bin 


init 


;oooiob) , 


RW ACCESS BIN 


init 


;oioiob) , 


re"access"bin 


init 


[01100b) , 


REfif_ACCESS_BIN 


init 


:oi i iob) , 


S ACCESS BIN 


init 


:01000b) , 


M ACCESS~BIN 


init 


:oooiob) , 


a~access~bin 


init 


:ooooib) , 


SA ACCESS BIN 


init. 


[01001b) , 


SM~ACCESS BIN 


init 


[01010b) , 


SM"5 ACCESS BIN 


init 


[01011b)) 



fixed bin (5) internal static options (constant); 
/* END INCLUDE FILE ... access mode values .incl ,p!1 */ 
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CREATING STORAGE SYSTEM ENTITIES 

• hcs__$append_ link 

call hcs_$append_link (dir^name, entryname, path, code); 

1 CREATES A LINK IN SPECIFIED DIRECTORY 



J LINK'S TARGET NEEDN'T EXIST AT CREATION TIME (CODE OF ZERO STILL 
RETURNED) 



APPEND PERMISSION REQUIRED ON CONTAINING DIRECTORY 



Not To Be Reproduced 10-11 F15C 



DELETING SEGMENTS, DIRECTORIES, AND LINKS 

• delete_ 

HAS TWO ENTRY POINTS 

I del ete_$ path 

GIVEN AN ENTRYNAME, DELETES SEGMENTS, MSFs , DIRECTORIES, 
AND LINKS 

I delete__ $ptr 

GIVEN A POINTER, DELETES SEGMENTS ONLY 

i call delete_$path (dir_name, entryname, switches, caller, code); 

1 call delete__$ptr ( seg_ptr , switches, caller, code); 
1 DIRECTORY TO BE DELETED NEED NOT BE EMPTY 

I UNSNAPS ANY LINKS THIS PROCESS HAS SNAPPED TO THE OBJECTS DELETED 

I NOTE: delete CAN'T PREVENT DISASTER WHEN ONE PROCESS DELETES 
ANOTHER'S SHADED SEGMENT 



J THE 6 BIT INPUT VARIABLE 'switches' MAKES THIS SUBROUTINE EXTREMELY 
FLEXIBLE 

I SEE THE SUBROUTINES MANUAL FOR DETAILS OF THE 6 SWITCHES 
(force_sw, question_sw, directory^ sw, segment^ sw, iink__sw, 
chase sw) ™ ~* 
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OBTAINING STATUS INFORMATION 



• THE FOLLOWING 4 ENTRY POINTS RETURN STATUS INFORMATION FOR A DIRECTORY 
ENTRY (LISTED IN ORDER OF INCREASING COMPLEXITY) 

^> hcs__$status_mins 

— ^ hcs_$status_minf 

hcs_$status__ 

*hc s_$ st a tus^long 

D ALL THE ABOVE ENTRY POINTS HAVE A CURIOUS ACCESS REQUIREMENT 

! INFORMATION IS RETURNED IF CALLER HAS STATUS ON THE CONTAINING 
DIRECTORY, OR NON-NULL ACCESS ON THE ENTRY 

I ENTRYNAMES ARE NOT RETURNED UNLESS THE CALLER HAS STATUS ACCESS 
ON THE CONTAINING DIRECTORY 



I TO THE STATUS ENTRY POINTS, DIRECTORIES AND MULTI-SEGMENT FILES 
t c\c\v mcMTTrar 



I THE ONLY DISTINGUISHING ATTRIBUTE IS THE BIT COUNT 
1 BIT COUNT = FOR A DIRECTORY 
I BIT COUNT = NUMBER OF COMPONENTS FOR A MSF 
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OBTAINING STATUS INFORMATION 



# hcs $ status minf 



Q call hcs_$status_minf (dir__ name, entryname, chase__sw, 

type, bit count, code); 



I RETURNS BIT COUNT AND ENTRY TYPE OF ENTRY, GIVEN A PATH 



I • TYPE OF ENTRY: 

MEANS link 

1 MEANS segment 

2 MEANS msf OR directory 



D OFTEN USED WHEN TRYING TO DISTINGUISH BETWEEN DIR AND MSF 



• hcs $ status mins 



D call hcs_$status_mins ( seg_ptr , type, bit__couflt, code); 



I RETURNS BIT COUNT AND ENTRY TYPE OF A SEGMENT GIVEN A POINTER TO 
THE SEGMENT 
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OBTAINING STATUS INFORMATION 



# hcs $ status 



call hcs_$status__ (dirv_name, entryname, chase sw, status ptr , 

status_area__ptr , code); 



I RETURNS INFORMATION ABOUT A SEGMENT, DIR, MSF, OR LINK: 

I INFORMATION INCLUDES ENTRY TYPE, DATE TIME CONTENTS LAST 
MODIFIED, DATE TIME LAST USED, NUMBER OF RECORDS USED, USER'S 
RAW MODE, USER'S EFFECTIVE MODE AND ENTRYNAMES (NO BIT COUNT) 



D CALLER MUST PROVIDE 

I POINTER TO CALLER-ALLOCATED INFO STRUCTURE 



I POINTER TO CALLER-DESIGNATED AREA TO CONTAIN "names" (IF NULL, 
NO NAMES RETURNED) 
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OBTAINING STATUS INFORMATION 



/» — BEGIN include file status_structures.incl.pl1 */ 

/* Revised from existing include files 09/26/78 
by C. D. Tavares */ 

/* This include file contains branch and link structures 
returned by hcs_$status_ and hcs__$status_long . */ 

del 1 status_branch aligned based ( status^ptr) , 
2 short aligned , 

3 type fixed bin (2) unaligned unsigned, 

/* seg , dir, or link */ 
3 nnames fixed bin (16) unaligned unsigned, 

/* number of names */ 
3 names_relp bit (18) unaligned, 

/* "see entry_names del */ 
3 dtcm bit (36) unaligned, 

/* date/time contents last modified */ 
3 dtu bit (36) unaligned, 

/* date/ time last used */ 
3 mode bit (5) unaligned, 

/* caller's effective access */ 
3 raw mode bit (5) unaligned, 

/* r caller's raw "rew" modes */ 
3 padl bit (8) unaligned, 
3 records_used fixed bin (18) unaligned unsigned, 

/* number of NONZERO pages used */ 

/* Limit of information returned by hcs_$status_ */ 

2 long aligned, 

bit (36) unaligned , 
date/ time last dumped */ 
bit (36) unaligned, 
date/time branch last modified */ 
bit (36) unaligned, 
logical volume ID */ 
3 current length fixed bin (12) unaligned unsigned. 

/* number of last page used */ 
3 bit count fixed bin (24) unaligned unsigned, 

/* reported length in bits */ 
3 pad2 bit (8) unaligned , 
3 copy__switch bit (1) unaligned, 

/•"""copy switch */ 
3 tpd switch bit (1) unaligned, 

/ T transparent to paging device switch */ 
3 mdir_switch bit (1) unaligned, 

/* — is a master dir */ 
3 damaged_switch bit (1) unaligned, 

/* salvager warned of possible damage */ 
13 synchronized switch bit- (1 ) unaligned ; 

3 pad3 bit (5) unaligned, 
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3 


dtd 




/* 


3 


dtem 




/* 


3 


Ivid 




/* 



OBTAINING STATUS INFORMATION 



3 ring brackets (0:2) fixed bin (6) unaligned unsigned, 
3 uid Bit (36) unaligned; /* unique ID */ 

del 1 status link aligned based ( status_ptr) , 

2 type fTxed bin (2) unaligned unsigned, /* as above */ 

2 nnames fixed bin (16) unaligned unsigned, 

2 names__relp bit (18) unaligned, 

2 dtem "Bit (36) unaligned, 

2 dtd bit (36) unaligned, 

2 pathname^length fixed bin (17) unaligned, 

/* see pathname */ 
2 pathname_relp bit (18) unaligned; /* see pathname */ 

del status__entry names ( status_branch. nnames) 
character T32) aligned based 

(pointer ( status_area_ptr , status^ branch. names_relp) ) , 
/* array of names returned */ " 
status__pathname character ( status_link.pathname_length) 
aligned based 

(pointer ( status_area__ptr , status_link.pathname_relp) ) , 
/* link target~path"~*/ 
status_area_ptr pointer, 
status_ptr pointer; 

del (Link initial (0), 

Segment initial (1), 

options (constant); 
/* values for type fields declared above */ 

/* -__ END include file status_structures.incl.pl1 - — */ 
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OBTAINING STATUS INFORMATION 



• hcs $status long 



call hcs $status_long (dir__name, entryname, chase_sw, status_ptr , 
"" "" status_area_ptr , code); 



I RETURNS EVERYTHING hcs_$status_ RETURNS PLUS: 

I DATE-TIME-LAST-DUMPED (SEGS ONLY) 

1 CURRENT LENGTH IN 1024-WORD UNITS (SEGS, MSFS) 

Q BIT COUNT (SEGS, MSFS) 

Q PHYSICAL VOLUME ID OF STORAGE DEVICE ON WHICH ENTRY CURRENTLY 
RESIDES 

I COPY AND DAMAGED SWITCH VALUES 

SEE THE switch_on and switch_off COMMANDS (AG92) 

Q RING BRACKETS 

I SEGMENT UNIQUE ID 
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OBTAINING STATUS INFORMATION 



* OTHER ENTRY POINTS THAT RETURN STATUS TYPE INFORMATION 1 



I he s__$get__ author , hcs_$get_bc_author 

D hcs__$get_ max_length, hcs_$get_max_length_seg 

Q hcs__$get_safety_sw, hcs_$get_safety_sw_seg 

fl hes $get link target 



• TO OBTAIN STATUS INFORMATION FOR ARCHIVE COMPONENTS SEE 






Q archive_$list_components 

fl archive_$next_component_info 



1 

COVERED IN MULTICS COURSE F15D 
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OBTAINING STATUS INFORMATION 



AN EXAMPLE 



Status: proc; 

del 1 status_branch aligned based ( status_ptr) , 

2 type fixed bin (2) unaligned unsigned, 

2 nnames fixed bin (16) unaligned unsigned, 

2 names_relp bit (18) unaligned, 

2 dtcm bit (36) unaligned, 

2 dtu bit (36) unaligned, 

2 mode bit (5) unaligned, 

2 rawjnode bit (5) unaligned, 

2 padl bit (8) unaligned, 

2 records used fixed bin (18) unaligned unsigned; 
del status__entry names (status branch. nnames) character (32) aligned 

based (pointer ( get_syste"m_free_area_() , status_branch.names_relp) ) ; 
del pointer builtin; 

del get — system_free_area_ entryO returns( ptr) ; 
del sta"tus_ptr ptr ; 
del ( ioa , 

com~err ) entry options (variable); 
del hes $status_ entry (char (*), char (*) , fixed bin (1), ptr, 

ptr, fixed bin (35)); 
del code fixed bin (35); 
del i; 

allocate status branch; 

call hcs_$status_ (">udd>MEDclass>F15C" , "si", 0, status_ptr , 

get_system__ free_area__() , code) ; 
if code "= - - 

then do; 

call com_err_ (code, "Status"); 
return ; ~* . 
end /* then do */; 

call ioa_ (""/si is a *[ link*; segment"; directory*] with *d names:", 

status_branch.type + 1, status__branch. nnames) ; 
do i s 1 to status branch, nnames; 

call ioa_(" a", status_entry_names( i) ) ; 

end /* do i~**/; 

end /* Status */; 
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OBTAINING STATUS INFORMATION 
AN EXAMPLE 



r 15:00 0.148 19 
! Status 

s1 is a directory with 2 names: 

Student 01 

s1 
r 15:00 0.124 6 
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SECURITY 



• MULTICS HAS THREE ACCESS CONTROL MECHANISMS 



I THE ACCESS CONTROL LIST MECHANISM (ACLS) 



D THE ACCESS ISOLATION MECHANISM (AIM) 



THE RING MECHANISM 



• hcs AND OTHER SUBROUTINES ENABLE US TO MANIPULATE THESE MECHANISMS 
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ACCESS CONTROL LISTS 



hcs $add acl entries 



D call he s_$ ad d_acl_ entries (dir_name,' entryname, acl_ptr , 

~ acl_count, code); 



1 ADDS OR CHANGES ("SETS") ACL ON A SEGMENT (rewn) 

CALLER MUST ALLOCATE AND FILL IN AN ARRAY OF STRUCTURES 

1 "MATCHING" ACCESS NAMES ACCEPTABLE TO THE set acl COMMAND ARE 
NOT ACCEPTABLE 

I SEE msfjnanager_$acl_add FOR MULTI-SEGMENT FILES 1 



hcs $add dir acl entries 



call he s_$add_dir_acl_en tries (dir^name, entryname, acl_ptr , 

acl~count, code); 



J ADDS OR CHANGES ("SETS") ACL ON DIRECTORIES (sman) 



Q SIMILAR TO hcs_$add_acl_entries EXCEPT STRUCTURE MISSING 
extended mode "* "" 



1 

COVERED IN MULTICS COURSE F15D 
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ACCESS CONTROL LISTS 



/* Begin include file — acl__structures.incl.pl1 BIM 3/82 */ 
/* format: style3 */ 

declare acl__ptr pointer; 

declare acl_count fixed bin; 

declare 1 segment_acl aligned based (acl_ptr), 

2 version fixed bin, 

2 count fixed bin, 

2 entries (acl^count refer ( segment_acl .count) ) 

aligned like segment_acl_entry; 

declare 1 segment_acl_entry aligned based, 

2 access_name character (32) unaligned, 

2 mode bit (36) aligned, 

2 extended_mode bit (36) aligned, 
2 status_code fixed bin (35); 

declare 1 segment__acl_array (acl__count) aligned like 

segment_acl_entry based (acl_ptr)-; 

declare 1 directory^acl aligned based (acl_ptr), 

2 version"" fixed bin, 

2 count fixed bin, 

2 entries (acl_count refer (directory_acl .cour 

aligned like directory_acl_entry; 

declare 1 directory_acl_entry based, 

2 access name character (32) unaligned, 

2 mode ~ bit (36) aligned, 

2 status_code fixed bin (35); 

declare 1 directory_acl array (acl count) aligned like 

directory_ael_entry based (acl_ptr); 

declare 1 delete_acl_entry aligned based, 

2 access__name character (32) unaligned, 

2 status~code fixed bin (35); 

declare 1 delete acl based (acl_ptr) aligned, 

2 versTon fixed bin, 

2 count fixed bin, 

2 entries (acl_count refer ( delete_acl .count) ) 

aligned like delete_acl_entry ; 

declare 1 delete^acl^array (acl_count) aligned like 

delete__acl__entry based (acl_ptr); 

declare ACL_VERSI0N_1 internal static fixed bin init (1) 
~" options (constant); 

/* End include file acl_structures.incl.pl1 */ 
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ACCESS CONTROL LISTS 



hcs $delete acl entries 



fl call he s_$ del ete_acl_en tries (dir_name, entryname, acl_ptr , 
"** acl~count, code); 



I DELETES ONE OR MORE ENTRIES FROM A SPECIFIED SEGMENT'S ACL 

1 USES A STRUCTURE ALLOCATED BY CALLER 

I "MATCHING" ACCESS NAMES ACCEPTABLE TO THE delete acl COMMAND 
ARE NOT ACCEPTABLE TO hcs_$delete_acl_entries 

fl SEE msf__manager_$acl_delete FOR MULTI-SEGMENT FILES 1 



hcs $delete dir acl entries 



call he s_$ del ete — dir_acl_en tries ( dir_ name, entryname, acl_ptr , 

~~ ~" acl~*count, code); 



I DELETES ONE OR MORE ENTRIES FROM A SPECIFIED DIRECTORY 'S ACL 
I OTHERWISE SIMILAR TO hcs $delete acl entries 



1 

COVERED IN MULTICS COURSE F15D 
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ACCESS CONTROL LISTS 



• hcs $list acl 



call hcs_$list_acl (dir_name., entryname, area__ptr, 

~" area__ ret_ ptr , acl_ptr , acT_count, code); 



I RETURNS ALL OR PART OF A SEGMENT'S ACL IN A "segment acl' STRUCTURE 
(SAME STRUCTURE AS USED BY hcs $add acl entries) 



THERE ARE TWO DIFFERENT WAYS TO USE THIS ENTRY POINT: 

I IF ENTIRE ACL REQUIRED: 

I SET "area^ptr" NON-NULL AND EXPECT BACK "acl^count" AND 
" area_ret3tr" 

Q SUBROUTINE ALLOCATES AN ARRAY OF STRUCTURES 

I IF JUST SOME MODE ENTRIES REQUIRED: 
I SET "area_ptr" NULL 

I USER ALLOCATES AN ARRAY OF PARTIALLY FILLED IN STRUCTURES 
1 PASS A PTR TO THIS ARRAY (acl_ptr) 
MODES AND CODES WILL HAVE BEEN FILLED IN UPON RETURN 



hcs $list dir acl 



Q call hcs__$list_dir_acl (dir_name, entryname, area__ptr, 

"" " area_ret_ptr , acl__ptr , acl_count, code); 



I RETURNS ALL OR PART OF A DIRECTORY'S ACL 

1 SIMILAR TO hcs_$list_acl EXCEPT USES dir_acl STRUCTURE 
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ACCESS CONTROL LISTS 



• hcs $ replace acl 



Q call hcs_$replace_acl (dir_name, entryname, acl_ptr , acl_count, 
~" no_sysdaemon_sw, code); 



I REPLACES ENTIRE ACL FOR A SEGMENT WITH A USER-SUPPLIED ONE 

I USES SAME STRUCTURE AS hcs__$add_ acl_entries AND hcs_$list_acl 

Q CAN (OPTIONALLY) ADD "rw" FOR * .Sys Daemon .* 

CAN BE MADE TO DELETE ENTIRE ACL (IF acl countsO) 



hcs $replace_dir_acl 



call hcs_$replace_dir_acl ( dir__ name, entryname, acl__ptr , 

acl~count, no_sysdaemon_sw, code); 



1 REPLACES ENTIRE ACL FOR A DIRECTORY 

I USES SAME STRUCTURE AS hcs_$ % dd_dir_acl_entries AND 
hcs__$list — dir_acl "*" 

D CAN (OPTIONALLY) ADD "sma" FOR * .SysDaemon .* 

CAN BE MADE TO DELETE. ENTIRE ACL 
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ACCESS CONTROL LISTS 

• he s_$ f s_get_mod e 

1 call hcs — $fs__ get_mode ( seg_ptr , mode, code); 



I RETURNS THE EFFECTIVE ACCESS MODE (rew) OF THE CALLER ON A SPECIFIED 
SEGMENT 

■ 

D TAKES INTO ACCOUNT ACL, RING BRACKETS AND CURRENT VALIDATION 
LEVEL 

I NOTE: SINCE A POINTER IS PASSED, SEGMENT MUST HAVE BEEN MADE 
KNOWN, WHICH IMPLIES USER HAS NON-NULL ACCESS 



• get_group_id_ 

Q user_id = get_group__id_ (); 

I RETURNS IN A char(32) nonvarying Personid .Projectid .tag 



get_group__ id_$tag_star 

D user_id s get__group_id_$tag_star (); 

I RETURNS Personid .Projectid .* 
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WORKING , DEFAULT, AND PROCESS DIRECTORIES 

change_wdir_ 

i call change_wdir_ (path, code); 

I CHANGES THE WORKING DIRECTORY TO THE SPECIFIED DIRECTORY 

1 REQUIRES ABSOLUTE PATHNAME 

1 COMMAND INTERFACE: cwd 



get__ wdir_ 

E working_dir s get_wdir_ (); 



I RETURNS THE ABSOLUTE PATHNAME OF THE USER'S CURRENT WORKING 
DIRECTORY IN A char(l68) nonvarying 



Q COMMAND INTERFACE: pwd 



Not To Be Reproduced 10-29 F15C 



WORKING, DEFAULT, AND PROCESS DIRECTORIES 



• get_pdir_ 

Q process__dir s get_pdir_ (); 



I THIS FUNCTION RETURNS THE ABSOLUTE PATHNAME OF THE USER'S PROCESS 
DIRECTORY IN A char( 1 68)nonvarying 



COMMAND INTERFACE: pd 



• get__ default_wdir_ 

D default_wdir = get_default_wdir_ (); 



I RETURNS THE ABSOLUTE PATHNAME OF THE CALLER'S DEFAULT WORKING 
DIRECTORY IN A char(l68) nonvarying 



COMMAND INTERFACE: pdwd 
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WORKING , DEFAULT , AND PROCESS DIRECTORIES 

• change_default_wdir_ 

1 call chang e_default_wdir_ (path, code); 



I CHANGES THE USER'S CURRENT DEFAULT WORKING DIRECTORY TO THE 
DIRECTORY SPECIFIED 



I COMMAND INTERFACE: cdwd 



Not To Be Reproduced 10-31 F15C 



MANIPULATING PATHNAMES 

• expand_pathname_ 

call expand_pathname__ (pathname, dirname, entryname, code); 



I CONVERTS A RELATIVE OR ABSOLUTE PATHNAME INTO A DIRECTORY PATHNAME 
AND AN ENTRYNAME 

I COVERED IN TOPIC 5 



expand_pathname_$add_suffix 



il call expand_pathname_$add_suffix (pathname, suffix, dirname, 
"" entryname, code); 



1 SAME AS expand pathname , BUT ALSO ADDS A SPECIFIED SUFFIX ONTO 
THE ENTRYNAME, "IF THAT SlJFFIX IS NOT ALREADY PRESENT 



expand^ pathname_$ component 



call ex pand_pathname__$ component (pathname, dirname, entryname, 
~" ~" componentname, code); 



1 EXPANDS A ^RELATIVE OR ABSOLUTE PATHNAME INTO A DIRECTORY NAME, 
AN ARCHIVE NAME, AND AN ARCHIVE COMPONENT PORTION (OR INTO A 
DIRECTORY NAME AND ENTRYNAME PORTION IF NO COMPONENT NAME IS 
PRESENT) 
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MANIPULATING PATHNAMES 



expand_pathname_$component_add_suffix 



II call expand == pathname_$component_add_suffix (pathname, suffix, 

dirname, "entryname, componentname, code); 



II SAME AS expand pathname $ component, BUT ALSO ADDS A SPECIFIED 
SUFFIX TO EITHER THE ENTRYNAME OR THE COMPONENT NAME, IF NOT 
ALREADY PRESENT 



^ • absolute__pathname_ 

Q call absolute_pathname_ (pathname, full_pathname, code); 

n o ninrpBTci • Oct « T»Ttrr7 rvo iBoniiiTr o* Tti»T» «c TiiTn oir joertr hit o»TUiiriVMi7 



absolute_pathname_$add_suffix 



Q call absolute_pathname_$add_suffix (pathname, suffix, 

~" full pathname, code); 



I SAME AS absolute_pathname , BUT ALSO ADDS A SPECIFIED SUFFIX IF 
THAT SUFFIX IS NOT ALREADY PRESENT 
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MANIPULATING PATHNAMES 

• get^shortest^path^ 

Q shortest^ path = get_shortest_path_ (original_path) ; 



pathname^ 

fl path = pathname^ (dirname, entryname); 



I GIVEN A DIRECTORY NAME AND AN ENTRY NAME, RETURNS THE PATHNAME 
OF THE ENTRY IN A char (168) 

IF THE RESULTING PATHNAME IS >1 68 CHARACTERS, THE LAST 20 
CHARACTERS OF THE RESULT ARE SET TO "<PATHNAME TOO LQNG>" 



• pathname $component 



D path = pa thname_$ component (dirname, entryname, component_name) ; 



I GIVEN A DIRECTORY NAME, AN ENTRY NAME, AND OPTIONALLY, AN ARCHIVE 
COMPONENT NAME, CONSTRUCTS A PATHNAME OR AN ARCHIVE COMPONENT 
PATHNAME 

I IF COMPONENT NAME IS NULL AND THE RESULTING PATHNAME IS >1 68 
CHARACTERS, THE LAST 20 CHARACTERS OF THE PATHNAME ARE SET TO 
"<PATHriAHE TOO LONG>" 

IF COMPONENT NAME IS NOT NULL AND THE RESULTING PATHNAME IS 
>1 94 CHARACTERS, THEN THE LAST 20 CHARACTERS OF THE 
dirname> entryname PORTION OF THE ARCHIVE PATHNAME ARE CHANGED 
TO "KPATHNAME TOO LONG>" AND THE comDonent name REMAINS IN 
THE PATHNAME 
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MANIPULATING PATHNAMES 



• pathname_$component_check 



B call pathname_$component_ > check (dirname, entryname, 

component_name, path, code); 



I SAME AS pathname $ component EXCEPT A STATUS CODE INDICATES 
TRUNCATION INSTEAD" OF AN INVALID PATHNAME CONTAINING 'KPATHNAME 
TOO LONG>" 



• NOTE: NONE OF THE PREVIOUS SUBROUTINES CHECK TO SEE IF THE ENTRY 
EXISTS 
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ANIPULATING PATHNAMES 



YOU ARE NOW READY FOR WORKSHOP 
#7 
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Topic XI MORE MULTICS STORAGE SYSTEM SUBROUTINES Topic XI 

OBJECTIVES: 

Upon completion of this topic* students should be able to! 

1. Move entries from one place in the storase system to another. 



2. Change the lengths and names of entries in the storase 
system. 



3. Add and remove entries to and from the user's name space. 



Multics XI-1 F15C 



NAMING AND MOVING DIRECTORY ENTRIES 



• hcs $chname file 



D call hcs_$chname_file (dir_name, entryname, "oldname, 
** newname, code); 



I ADDS, DELETES, OR CHANGES NAMES OF SEGMENTS, DIRECTORIES, MSFS, 
OR LINKS (SPECIFIED BY NAME) 

EITHER oldname OR newname (BUT NOT BOTH) MAY BE null ('"') 

MODIFY PERMISSION ON CONTAINING DIRECTORY REQUIRED 



# hcs_$chname_seg 

I call hcs_$chname_seg ( seg_ptr , oldname, newname, code); 



I ADDS, DELETES, OR CHANGES NAMES OF A SEGMENT, GIVEN A POINTER TO 
IT 



I OTHERWISE SIMILAR TO hcs $chname file 
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NAMING AND MOVING DIRECTORY ENTRIES 



hcs $ f s move file 



call hcs_$fs_move_file ( from_dir , from__ entry, at — sw, 
"" ~* to_dir , to^entry, code); - 



I MOVES CONTENTS OF ONE SEGMENT TO ANOTHER SEGMENT 

I at_sw HAS 2 BITS (fixed bin(2)) 

D THE APPEND BIT ON FORCES CREATION OF NEW SEGMENT IF IT 
DOESN'T EXIST 

I THE TRUNCATE BIT ON FORCES TRUNCATION OF NEW SEGMENT IF IT 
EXISTS 

I OLD (ZEROED OUT) SEGMENT REMAINS 
I RECORD LENGTH = 
I BIT COUNT NOT CHANGED 

I NEW SEGMENT'S BIT COUNT NOT ADJUSTED 

I ACCESS REQUIRED 

I READ AND WRITE ON OLD SEGMENT 

I READ, WRITE ON NEW SEGMENT (IF IT EXISTS) 

H APPEND ON NEW SEGMENT'S CONTAINING DIRECTORY (IF SEG MUST 
BE CREATED) 

FOR A SHORT TIME, 2 IMAGES EXIST (POSSIBLE QUOTA PROBLEM) 
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NAMING AND MOVING DIRECTORY ENTRIES 

• he s_$ f s_mov e_seg 

1 call hcs_$fs_move_seg ( from_ptr , tc_ptr, trun_sw, code); 

I MOVES CONTENTS OF ONE SEGMENT TO ANOTHER, GIVEN POINTERS TO EACH 
I trun_sw HAS ONLY ONE BIT 
I OTHERWISE SIMILAR TO hes $ f s move file 
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AFFECTING THE LENGTH OF A FILE 

• hcs_$truncate — file 

call hcs_$truncate_file (dir_name, entryname, length, code); 

1 TRUNCATES A SEGMENT TO A SPECIFIED LENGTH (IN WORDS), GIVEN ITS 
NAME AND CONTAINING DIRECTORY NAME 

I TRAILING FULL PAGES ARE DISCARDED 

I ZEROES ARE STORED (IN LAST PAGE) BEYOND SPECIFIED LENGTH 

I WRITE. PERMISSION ON TARGET REQUIRED 

1 THE BIT COUNT IS NOT SET (USE EITHER hcs_$set_bc OR 
adjust_bit_count_) 

truncate COMMAND PERFORMS BOTH hcs_$ truncate_file AND 
he s $set be 
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AFFECTING THE LENGTH OF A FILE 



• hcs $set be 



call hcs_ $set_bc (dir_name, entryname, bit_count, code); 



SETS THE BIT COUNT OF A SEGMENT TO A SPECIFIED NUMBER, GIVEN ITS 
NAME AND CONTAINING DIRECTORY 



I ALSO SETS BIT COUNT AUTHOR TO USER ID OF CALLER 

I WRITE PERMISSION ON SEGMENT REQUIRED 

I MODIFY PERMISSION ON DIRECTORY NOT REQUIRED 

I COMMAND INTERFACE: set bit count (sbc) 



aa j ust_Di t_co un t_ 



call adjust_bit_count_ (dir__ name, entryname, char_sw, 
"" bit~count, code); 



I SETS THE BIT COUNT TO THE LAST NON-ZERO WORD OR BYTE 
I WORKS ON SEGMENTS AND MULTISEGMENT FILES 



I char sw DETERMINES WHETHER THE BIT COUNT IS ADJUSTED TO THE 
LAST~WORD OR CHARACTER 



I COMMAND INTERFACE: ad just_bit_count (abc) 
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AFFECTING THE LENGTH OF A FILE 



• terminate_file_ 

Q call terminate_file_ (seg_ptr, bit_count, switches, code); 

1 PERFORMS COMMON OPERATIONS OFTEN NECESSARY AFTER A PROGRAM HAS 
FINISHED USING A SEGMENT, SUCH AS 

1 SETTING THE BIT COUNT 

I TRUNCATING THE SEGMENT 

I ENSURING THAT BITS IN THE LAST WORD OF THE SEGMENT AFTER THE 
BIT COUNT ARE ZERO 

I TERMINATING A NULL REFERENCE NAME 

I ENSURING THAT ALL MODIFIED PAGES OF THE SEGMENT ARE NO LONGER 
IN MAIN MEMORY 

I USES THE terminate file switches STRUCTURE 
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AFFECTING THE LENGTH OF A FILE 



/» BEGIN INCLUDE FILE ... terminate file.inol.pH 
/* format: style2,*inddcls,idind32 "*/ 



*/ 



declare 


1 terminate^ file_switche; 


s based , 




2 truncate" 


bit 


(1 ) unaligned , 




2 set_bc 


bit 


(1) unaligned, 




2 terminate 


bit 


(1 ) unaligned , 




2 force — write 


bit 


(1 ) unaligned , 




2 delete" 


bit 


(1 ) unaligned; 


declare 


TERM_FILE_TRUNC 


bit 


(1 ) internal 




~" ""static options 


(constant) 


initial ( "1 "b) ; 


declare 


TERM_FILE_BC 


bit 


(2) internal 




~ static options 


(constant) 


initial ("01"b); 


declare 


TERM_F ILE_TR UNC_BC 


bit 


(2) internal 




~~ static" options 


(constant) 


initial ("11"b); 


declare 


TERM_FILE_TERM 


bit 


(3) internal 




"static options 


( constant) 


initial ("001"b); 


declare 


TERM_FILE_TRUNC_BC_TERM 


bit 


(3) internal 




""static options 


( constant) 


initial ( "1 1 1 "b) ; 


declare 


TERM_FILE_FORCE_WRITE 


bit 


(4) internal 




static options 


( constant) 


initial ( ! '0001"b); 


declare 


TERM_FILE_DELETE 


bit 


(5) internal 




""static options 


(constant) 


initial ("00001 "b) ; 



/» END INCLUDE FILE 



terminate^ file.incl .pl1 */ 



terminate file SHOULD NEVER BE CALLED FROM A CLEANUP HANDLER 
WITH THE truncate OR set_bc SWITCHES ON ( seg ptr MAY CONTAIN AN 
INVALID SEGMENT NUMBER) 



force_write SHOULD BE USED ONLY WHEN DATA INTEGRITY IS ABSOLUTELY 
ESSENTIAL AS IT MAY INTRODUCE A SUBSTANTIAL REAL TIME DELAY IN 
EXECUTION 
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MANIPULATING THE ADDRESS AND NAME SPACES 



• DEFINITION OF TERMS 



I ADDRESS SPACE IS 



I THE PER-PROCESS COLLECTION OF SEGMENTS THAT CAN BE DIRECTLY 
REFERENCED VIA HARDWARE 



I EXPANDING AND CONTRACTING DURING A PROCESS' LIFE 

I A COLLECTION OF "KNOWN" SEGMENTS 

I REFLECTED IN THE DSEG (AND KST) 

Q MANAGED 

I AUTOMATICALLY BY THE DYNAMIC LINKER 

5 IMPLICITLY, BY A CALL TO SOME SYSTEM COMMAND 

EXAMPLE: print my_dir>my_seg 

EXPLICITLY, BY USER CALLS TO SYSTEM COMMANDS OR SUBROUTINES 
THAT MANAGE THE ADDRESS SPACE 
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MANIPULATING THE ADDRESS AND NAME SPACES 

II NAME SPACE IS 

I THE PER-PROCESS COLLECTION OF "REFERENCE" NAMES (OPTIONALLY) 
ASSOCIATED WITH EACH "KNOWN" SEGMENT 

I EXPANDING AND (RARELY) CONTRACTING DURING A PROCESS' LIFE 

I REFLECTED IN THE REFERENCE NAME TABLE (RNT) 

D AN IMPORTANT PART OF SEARCH RULES (INITIATED SEGMENTS LIST) 

D MANAGED 

I AUTOMATICALLY BY THE DYNAMIC LINKER 

I EXPLICITLY, BY USER CALLS TO SYSTEM COMMANDS OR SUBROUTINES 
THAT MANAGE THE NAME SPACE 

I MAKING-KNOWN INVOLVES 

I DEVELOPING A POINTER TO A SPECIF IED4EGMENT (ASSIGNING A SEGMENT 
NUMBER) ¥ 

D ADDING AN ENTRY TO THE KST AND DSEG 

I INITIATING (A REFERENCE NAME) INVOLVES 
I EXPANDING THE PROCESS' NAME SPACE 
5 ADDING AN ENTRY TO THE RNT 
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MANIPULATING THE ADDRESS AND NAME SPACES 

D TERMINATING (A REFERENCE NAME) INVOLVES 
I CONTRACTING THE PROCESS 1 NAME SPACE 
I REMOVING AN ENTRY FROM THE RNT 

1 MAKING-UNKNOWN INVOLVES 

I MAKING A. PREVIOUSLY VALID SEGMENT NUMBER INVALID 

I FREEING UP THAT SEGMENT NUMBER FOR FUTURE REASSIGNMENT 
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MANIPULATING THE ADDRESS AND NAME SPACES 



• NOTES 



I INITIATING A REFERENCE NAME MAY TRIGGER THE MAKING-KNOWN OF A 
SEGMENT 



I TERMINATING A REFERENCE NAME MAY TRIGGER THE MAKING-UNKNOWN OF A 
SEGMENT 



I AN UNKNOWN SEGMENT CAN NOT HAVE A REFERENCE NAME 



1 A KNOWN SEGMENT MAY HAVE A NULL REFERENCE NAME 



I PRESENCE IN THE RNT IMPLIES PRESENCE IN THE DSEG (AND KST) 



Not To Be Reproduced 11-11 F15C 



MANIPULATING THE ADDRESS AND NAME SPACES 



• TERMINATING SEGMENTS USING term_ 

term_$ term_ 

Q call term_$term_ (dir_path, entryname, code); 

I REMOVES ALL REFERENCE NAMES FROM RNT 

I REMOVES SEGMENT FROM CALLER'S ADDRESS SPACE 

I REMOVES SEGMENT FROM COMBINED LINKAGE SECTION 

I UNSNAPS LNKS IN COMBINED LINKAGE QECTION THAT CONTAIN 
REFERENCES TO THE SEGMENT 

I USER SUPPLIES dir_path AND entryname 

COMMAND INTERFACE: terminate ( tm) 

term_$seg_ ptr 

D call term_$seg_ptr ( seg__ptr , code); 

1 LIKE term_$term_, BUT ACCEPTS A PTR TO SEGMENT 
I COMMAND INTERFACE: terrainate_segno (tms) 

D term_$refname 
« 
call term^lrefname (ref_narae. code): 

1 LIKE term_$term_, BUT ACCEPTS A REFERENCE NAME 

I COMMAND INTERFACE: terminate refname (tor) 
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MANIPULATING THE ADDRESS AND NAME SPACES 



D term__$single_refname 

Q call term_$ sing le_ref name (refjsame, code); 

I REMOVES A SINGLE REFERENCE NAME FROM RNT 

I BEHAVES LIKE term_$refname (I.E. SEGMENT IS NOT MADE UNKNOWN) 
IFF REFNAME SPECIFIED WAS SEGMENT'S ONLY INITIATED REFNAME 

I COMMAND INTERFACE: terminate_single_refname (tmsr) 



D term_$unsnap 

fl call term__$.unsnap ( seg_ptr , code); 
I UNSNAPS LINKS ONLY 

I DOESN'T TERMINATE REFERENCE NAMES OR MAKE SEGMENT UNKNOWN 
I NO COMMAND LEVEL INTERFACE 
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MANIPULATING THE ADDRESS AND NAME SPACES 



• initiate file 



A MAKES A SEGMENT KNOWN WITH A NULL REFERENCE NAME 



I (PREVIOUSLY DISCUSSED IN TOPIC 5) 



terminate file 



TERMINATES A NULL REFERENCE NAME 



I (PREVIOUSLY DISCUSSED IN THIS TOPIC) 
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EXAMINING THE ADDRESS AND NAME SPACES 



• hcs__$fs_get_path_name 



call hcs_$fs_get_path_name ( seg_ptr , dir_name, ldn, 
"~ "" entryname, code); 



I GIVEN A POINTER TO A SEGMENT, RETURNS A PATHNAME FOR THE SEGMENT, 
WITH THE DIRECTORY AND ENTRYNAME PORTIONS SEPARATED (THE ENTRYNAME 
RETURNED IS THE PRIMARY NAME ON THE ENTRY) 



• hcs_$fs__get__ref_name 

I call hcs_$fs_get_ref_name ( seg_ptr , count, ref_name, code); 



I RETURNS A SPECIFIED (I.E., FIRST, SECOND, ETC.) REFERENCE NAME 
OF A SPECIFIED SEGMENT, GIVEN A POINTER TO THE SEGMENT 



hcs_$ fs_get_seg_ptr 

fl call hcs_$fs_get_seg_ptr (ref__name, seg_ptr , code); 



I GIVEN A REFERENCE NAME OF A SEGMENT , RETURNS A POINTER TO THE BASE 
OF THAT SEGMENT 
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PATHNAME , POINTER, REFERENCE NAME CONVERSION 
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PATHNAME , POINTER, REFERENCE NAME CONVERSION 



YOU ARE NOW READY FOR WORKSHOP 
#8 
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Topic XII COMMANDS AND ACTIVE FUNCTIONS Topic XII 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 



1. Describe the differences between a command and an active 
f un c t i o n . 



2. Write a command which takes a varyins number of arsumentsr 
validates them> and performs some task. 



3. Write an active function which accepts a varyins number of 
arsuments? validates them, and returns an appropriate value. 

4. Use Multics subroutines to report errors encountered durins 
execution of a command or active function. 



5. Use Multics subroutines to aciuire and release temporary 
workins storase. 



6. Use the Multics clock and timer functions. 
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COMMANDS 
CHARACTERISTICS OF A COMMAND 



A COMMAND PROCEDURE IS AN OBJECT PROGRAM WHICH IS DESIGNED TO BE 
INVOKED FROM COMMAND LEVEL 



A COMMAND PROCEDURE MUST OPERATE WITHIN STRICT OPERATIONAL LIMITATIONS, 
AND IT IS THESE LIMITATIONS THAT MAKE IT DIFFERENT FROM OTHER PROCEDURES 



MANY SYSTEM SUBROUTINES CALLED BY COMMAND PROCEDURES RETURN PL/I 
POINTER VALUES, THUS FORCING THE AUTHOR TO CODE THE COMMAND PROCEDURE 
IN PL /I 
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COMMANDS 
DIFFERENCES BETWEEN A COMMAND AND A PROGRAM 



• THE DIFFERENCES WHICH EXIST BETWEEN A COMMAND PROGRAM AND A REGULAR 
PROGRAM ARE DEFINED BY THE THREE RESTRICTIONS BELOW: 



I BECAUSE THE COMMAND IS CALLED BY THE MULTICS COMMAND PROCESSOR 
(OR A USER -DESIGNED COMMAND PROCESSOR) 

D INPUT ARGUMENTS ARE LIMITED TO 'nonvarying unaligned character 
strings' 

D HENCE, A COMMAND IS RESPONSIBLE FOR CONVERTING THESE STRINGS 
TO WHATEVER DATA TYPES ARE REQUIRED 



I A COMMAND CAN RECEIVE ONLY INPUT ARGUMENTS 

I THE COMMAND CANNOT CHANGE THE VALUE OF ANY OF THESE INPUT 
ARGUMENTS 



I THE COMMAND MUST BE PREPARED TO HANDLE AN ARBITRARY NUMBER OF 
ARGUMENTS - THERE ARE NO PARAMETER DECLARATIONS ALLOWED 

I IF THE COMMAND IS PASSED TOO MANY ARGUMENTS, IT MUST COMPLAIN 
AND ABORT (CONSIDER HOW THE SYSTEM HANDLES "pwd a") 



Q OTHER RULES FOR MULTICS SYSTEM COMMANDS 
I USE com err TO REPORT ERRORS 



ff nor \ir\ r»T /t T IC\ HlGT? A ** *% 4 *w A Mrs /■* /^mm ««H nnai*!f ^ 
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COMMANDS 
REPORTING ERRORS 



• WHEN A COMMAND PROCEDURE DETECTS SOME ERROR, IT IS RESPONSIBLE FOR 
REPORTING IT TO THE USER IN A STANDARD FASHION: 



I com err 



Q THE PRINCIPAL SUBROUTINE USED BY COMMANDS FOR PRINTING ERROR 
MESSAGES 



I IT IS GENERALLY CALLED WITH A NONZERO STATUS CODE TO REPORT 
SOMETHING UNUSUAL 



II IT MAY ALSO BE CALLED' WITH A CODE OF TO REPORT AN ERROR NOT 
ASSOCIATED WITH A STATUS CODE 

I declare com_err_ entry options( variable) ; 

call com__err_ (code, caller, control_string , argl , ..., 
~ ~ arg N) : 

I control string IS AN OPTIONAL ioa SUBROUTINE CONTROL STRING 
(INPUT) - 

Q argl , ..., argN ARE ioa SUBROUTINE ARGUMENTS TO BE 
SUBSTITUTED INTO THE control string (INPUT) 
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COMMANDS 
REPORTING ERRORS 



D THE ERROR MESSAGE PREPARED BY com_err_ HAS THE FORM: 

H caller: system_message user — message 

D FOR SYSTEM COMMANDS caller IS THE NAME OF THE PROGRAM 
DETECTING THE ERROR 

I EXAMPLE: (IF codes error table $wrong no of argsANDnargs 
= 5) ----- 

PL/I STATEMENT: 

call com_err_ (code, rt sample_command" , 

"VYou furnished *d args.", nargs); 

1 RESULT: 

sam pi e_ command : Wrong number of arguments supplied. 
You furnished 5 args. 

Q IF CODE s ONLY A user message IS PRINTED 
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COMMANDS 
COMMAND I/O 



• IN WRITING COMMAND PROCEDURES NO LANGUAGE LEVEL I/O STATEMENTS ARE 
EVER USED 



• STANDARD INPUT/OUTPUT IS DONE USING THE FOLLOWING SUBROUTINES: 

I ioa_ 

I USED FOR FORMATTING A CHARACTER STRING 

I iox_ 

D THE SUBROUTINE-LEVEL INTERFACE TO THE MULTICS I/O SYSTEM 



I command_query_ 

THE STANDARD SYSTEM PROCEDURE INVOKED TO ASK THE USER A QUESTION 
AND OBTAIN AN ANSWER 

•I IT PRINTS THE QUESTION ON THE USER'S TERMINAL, AND THEN READS 
THE 'user_Miput' SWITCH TO OBTAIN THE ANSWER 

1 declare command__query_ entry optionsC variable) ; 

call comffiand_query_ ( ptr , answer, caller, control_string , 

arg1_, ..., argN) ; 

I ptr POINTS TO THE query info STRUCTURE DESCRIBED ON THE 
FOLLOWING PAGE (INPUT) * 
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COMMANDS 
COMMAND I/O 



/• BEGIN INCLUDE FILE query__info.incl.pl1 TAC June 1, 1973 •/ 
/* Renamed to query info .incl.pl! 

and" cp escape control added, 08/10/78 WOS */ 
/* version number changed to 47 08/10/78 WOS */ 
/* Version 5 adds explanation__( ptr len) 05/08/81 S. Herbst */ 
/* Version 6 adds literal sw, prompt after explanation switch 

12715/82 S. Herbst */ 

del 1 query info aligned, 

/* "argument structure for command__query_ call */ 
2 version fixed bin, 

/* version of this structure - must be set, see below */ 
2 switches aligned, 

/* various bit switch values */ 
3 yes or_no sw bit (1) unaligned init ("0"b), 

f* not a yes-or-no question, by default */ 
3 suppress_name_sw bit (1) unaligned init ("0"b), 

/* do not suppress command name */ 
3 cp_escape__control bit (2) unaligned init ("0Q"b), 
/* obey static default value */ 

/* "oi « _> invalid, "10" -> don't allow, "11" -> allow */ 
3 suppress__spacing bit (1) unaligned init ("0"b), - 

/* whether to print extra spacing */ 
3 literal sw bit (1) unaligned init ("0"b), 

/* 0N~"=> do not strip leading/ trailing white space */ 
3 prompt after explanation bit (1) unaligned init ("0"b), 

/* 01 => repeat question after explanation »/ 
3 padd'ing bit (29) unaligned init ( n "b), 
/* pads it out to t word */ 
2 status code fixed bin (35) init (0), 

/* query not prompted by any error, ay default */ 
2 query_code fixed bin (35) init (0), 
/* currently has no meaning */ 

/* Limit of data defined for version 2 */ 

2 question iocbp ptr init (null ()), 

/* 10 switch to write question */ 
2 answer iocbp ptr init (null ()), 

/* 10 switch to read answer */ 
2 repeat__time fixed bin (71) init (0), 

/* repeat question every N seconds if no answer */ 

/* otherwise, no repeat will occur */ 
/* Limit of data, defined for version 4 */ 

2 explanation ptr ptr init (null ()), 

/* explanation of question to be printed if */ 

2 exDlanation len fixed bin (21) init (0); 

/» user answers "?" (disabled if ptr=null or len=0) */ 
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COMMANDS 
COMMAND I/O 



del query info version_3 fixed bin int static 

~" ~ options (constant) init (3) 

del query_info_version_4 fixed bin int static 

"~ ~ options (constant) init (4) 

del query info_version 5 fixed bin int static 

~* options (constant) init (5) 

del query info version_6 fixed bin int static 

"" options (constant) init (6) 

/* the current version number */ 

/* END INCLUDE FILE query_info.incl.pl1 */ 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 

cu_ 

USED TO MANIPULATE THE COMMAND ENVIRONMENT IN FUNCTIONS LIKE: 
I SETTING THE READY MESSAGE 
I CALLING THE COMMAND PROCESSOR 
I CHANGING THE COMMAND PROCESSOR 
I EXAMINING STACK FRAMES 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 



• THE FOLLOWING ENTRIES ARE USED TO OBTAIN THE ARGUMENTS PASSED TO 
THE COMMAND 



I cu_$arg_count 

1 call cu_$arg_count (arg_count, code); " 

I USED TO DETERMINE THE NUMBER OF ARGUMENTS SUPPLIED WHEN THE 
PROCEDURE WAS CALLED 

1 cu_$arg_ptr 

D call cu_$arg_ptr ( arg_no , arg_ptr , arg_len , code); 

I RETURNS A POINTER TO AND THE LENGTH OF ONE OF THE ARGUMENTS 

I arg_no IS AN INTEGER SPECIFYING THE NUMBER OF THE DESIRED 
ARGUMENT (INPUT) 

NOTE THAT A BASED VARIABLE IS NORMALLY USED FOR INPUT ARGUMENTS 
AND IS DECLARED AS FOLLOWS: 

I declare argument char( arg_len) based( arg_ptr) ; 
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COMMANDS 



OTHER SUBROUTINES USED IN WRITING COMMANDS 



• EXAMPLES 



sample_command : proc; 

del eu_$arg count entry( fixed bin, fixed bin(35)); - 

del nargs fixed bin; 

del error_table Iwrong^no^o^args fixed bm(35) external; 

del com_err ehiry optTons( variable) ; 

del code fixed bin(35); 

• • • 

call cu_$arg_count (nargs, code); 

if nargs *s 

then do; 

call com_err ( error_table_$wrong_no_of_args, 

"" "sample command"); 

return ; 

end /* then do */; 



sample_command2: proc; 

del cu_$arg ptr entry (fixed bin ,ptr .fixed bin(21 ) ,f ixed bin(35)); 

del argument char(arg len) based ( arg_ptr) ; 

del arg_len fixed binT21); 

del arg""ptr ptr: 

del code fixed bin(35); 

del (com err_, ioa_) entry options( variable) ; 

cail'eu $arg ptr (1, arg_ptr , arg_len , code); 
if code = 0" 

then do; j ^ inN 

call com__err_ (code, "sampie^eomaianu* ■■ j ; 

return; "*" 
end /* then do */; 
call ioa_( "First argument is * a" .argument) ; 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 

• THE FOLLOWING SUBROUTINES ARE USED FOR ARGUMENT CONVERSION: 

H expand__pathname_ 

fl call expand__ pathname^ (pathname, dirname, entryname, code); 

1 PREVIOUSLY DISCUSSED IN TOPICS 5 AND 10 

I NOTE THAT SOME CRITICAL MULTICS SUBROUTINES REQUIRE A PATHNAME 
ARGUMENT SPECIFIED IN TWO PORTIONS, THE DIRECTORY PATHNAME 
AND THE ENTRYNAME, AND THIS IS ONE OF THE MAIN REASONS 
expand_pathname_ IS AVAILABLE 

I cv_ptr_ 

D ptr_value = cv_ptr_ (vptr, code); 

I THIS FUNCTION CONVERTS A VIRTUAL POINTER TO A POINTER VALUE 
(A VIRTUAL POINTER IS A CHARACTER-STRING REPRESENTATION OF A 
POINTER VALUE, SUCH AS "foo$bar" OR ">udd>PROJ>PERS>seg ! 1 200") 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 

OTHER CONVERSION SUBROUTINES AND FUNCTIONS 

fl cv_bin_ 

cv_bin_$dec 
cv_bin_$oct 

Q cv_dec_, cv_dec_check_ 

cv_oct_, cv_oct_check_ 

D cv_hex_, cv_hex_check_ 

D cv_float_ 

S cv_float_double_ 

cv_ptr_$ terminate 

Q cv_entry__ 

cv_mode_ 

H c v__d ir_mod e_ 

Q cv_userid_ 

D cv_error_ 

D cv error $name 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 



This Page Intentionally left Blank 
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COMMANDS 
AN EXAMPLE OF A COMMAND 



how_long: proc; 

entry (fixed bin, fixed bin (35)); 

entry (fixed bin, ptr , fixed bin(21), fixed bin (35)); 
entry (char (*), char (*) , char (*), fixed bin (35)); 
entry (char(*), char(»), fixed bind), fixed bin(2), 

fixed bin(24), fixed bin(35)); 
bit (1) init ("0»«b); 
char (argl) based (argp); 
fixed bin; 
fixed bin(21); 
ptr; 

fixed bin (2); 
fixed bin (35); 
char (168); 
char (32); 

entry options (variable); 

char (8) static init ( "how_long") options (constant); 
fixed bin (24); 
builtin; 
__ ig_no__of_args fixed bin(35) external; 

/* check number of args */ 

call cu_$arg count (nargs, code); 
if (nargs < T) i (nargs > 2) 
then do; 

call com_err_ (error__table_$wrong_no__of_args, ME); 

return; ~" 

end /* then do */; 

/* evaluate args */ 

do i 4 s 1 to nargs; 

call cu_$arg_ptr (i, argp, argl, code); 



del 


cu_$arg__count 


del 


cu — $arg2ptr 


del 


ex"pand_pathname_ 


del 


he s_$ st a tus_min f 


del 


long 


del 


arg 


del 


(i, nargs) 


del 


argl 


del 


argp 


del 


type 


del 


code 


del 


dir 


del 


entry 


del 


( com_err_, 




ioa ) 


del 


ME 


del 


be 


del 


null 


del 


error table $wro 



if i = 1 
then do; 



call expand_pathname__ (arg, dir, entry, code); 
if code *= ~ 

then do; 



««1 1 nnrn at"!" ( i->r>H a MP" ^ • 

** «• .fa •>■ WW *»•• \*»w^^, - ■ V # , 

return; 
end /* then do */; 
call hes $status_minf (dir, entry, 1, type, be, code); 
if code "s ~* 
then do; 

call eom_err_ (code, ME); 
return; 
end /* then do */; 
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COMMANDS 



AN EXAMPLE OF A COMMAND 



be = bc/36; 
end /* then do */; 
else do; 

/* second arg must be -long or -lg */ 
if (arg = "-long") 1 (arg = "-lg") 
then long = "1"b; 
else do; 

call com_err_ (0, ME, "Control arg must be -long or -lg" 
return; 
end /* else do */; 
end /* else do */; 
end /* do i */; 

call ioa_("' ! ' [Number of words for "a> A a is ~; ~2s*3 ~i" , long, dir, entry, be) 

end /* how_long */; 

r 14:03 0.197 18 

! ho w_ long 

how~long: Wrong number of arguments supplied, 
r 14:04 0.183 11 



! how long how long 
aou 
r 14:04 0.105 



! how__long how_long.pl1 -lg 

Num"Ber of words for >user dir dir>MED>Jackson>15c>how long.pH is 544 
r 14:04 0.088 - - 

! how__long how_long.pl1 -short 

how long: Control arg must be -long or -lg 
r 1"4*:04 0.143 1 
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ACTIVE FUNCTIONS 



AN ACTIVE FUNCTION RETURNS A CHAR VARYING VALUE TO THE COMMAND 
PROCESSOR FOR SUBSTITUTION INTO THE COMMAND LINE 



II IT IS CALLED BY THE COMMAND PROCESSOR FOR THE PURPOSE OF RETURNING 
A VALUE TO THE COMMAND PROCESSOR 



D THE COMMAND PROCESSOR MUST PREPARE A LOCATION FOR THE RETURNED 
VALUE 



J THE ACTIVE FUNCTION MUST KNOW THIS LOCATION IN ORDER TO RETURN A 
VALUE 



AN ACTIVE FUNCTION DIFFERS FROM A STANDARD PROCEDURE IN THE THREE 
WAYS SPECIFIED FOR COMMANDS (TAKES ONLY CHARACTER-STRING ARGUMENTS, 
HANDLES ONLY INPUT ARGUMENTS, TAKES A VARYING NUMBER OF ARGUMENTS) 
AND HAS ONE ADDITIONAL DIFFERENCE: 



AN ACTIVE FUNCTION MUST RETURN A VARYING CHARACTER-STRING ARGUMENT 
TO THE COMMAND PROCESSOR IN- A LOCATION SPECIFIED BY THE COMMAND 
PROCESSOR 



• A COMMAND PROCEDURE CAN BE WRITTEN TO IMPLEMENT EITHER A COMMAND OR 
AN ACTIVE FUNCTION 



• SUCH A PROCEDURE'S EXECUTION DEPENDS ON THE MANNER IN WHICH IT WAS 
INVOKED 
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ACTIVE FUNCTIONS 
SUBROUTINES USED FOR WRITING ACTIVE FUNCTIONS 



• THE SUBROUTINES USED FOR WRITING AN ACTIVE FUNCTION MUST BE ABLE TO 
DETERMINE TWO VERY IMPORTANT THINGS: 



I THE LOCATION INTO WHICH IT SHOULD PLACE ITS RETURN VALUE 



I WHETHER OR NOT IT WAS INVOKED AS A ACTIVE FUNCTION 



cu $af arg count 



i call cu_$af_arg_ count (nargs, code); 



II RETURNS THE NUMBER OF INPUT ARGUMENTS 



! IF THE CALLER WAS NOT INVOKED AS AN ACTIVE FUNCTION, A NON-ZERO 
STATUS CODE IS RETURNED (error table $not act fen) 



• cu^af^arg^ptr 

13 call cu_$af_arg_ptr ( arg_no , arg__ptr , arg_len , code); 



1 OPERATES LIKE cu $arg ptr EXCEPT THAT IT RETURNS A NULL arg ptr 
IF IT WAS NOT CALLED fS AN ACTIVE FUNCTION 



I USUALLY USED IN WRITING PROGRAMS THAT CAN ONLY BE CALLED AS 
ACTIVE FUNCTIONS 
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ACTIVE FUNCTIONS 
SUBROUTINES USED FOB WRITING ACTIVE FUNCTIONS 



cu_$af_return_arg 



call cu^la^return^arg (nargs, rtn_string_ptr , max_length, 
~ ~" code) ; 



1 PERFORMS THE JOB OF cu$af_arg_count AND 



Q MAKES THE ACTIVE FUNCTION'S RETURN ARGUMENT AVAILABLE 

I Qtn stringfptp IS A POINTER TO THE VARYING STRING RETURN ARGUMENT 

0F^fmr~Kmw function (output) 




(max length) IS THE MAXIMUM LENGTH OF THE VARYING STRING POINTED 
T O "BY r n r forlng_.pt r (OUTPUT) 

IF THE CALLER WAS NOT INVOKED AS AN ACTIVE FUNCTION, A NON-ZERO 
STATUS CODE IS RETURNED (error_table_$not_act_fcn) 

Q NOTE THAT THE ACTIVE FUNCTION DECLARES ITS RETURN ARGUMENT AS 
FOLLOWS: 

declare return_string char (max_length) varying 

based ( rtn_string_ptr) ; 
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ACTIVE FUNCTIONS 
REPORTING ERRORS 



• AN ACTIVE FUNCTION USES A DIFFERENT SUBROUTINE FOR REPORTING ERRORS 
TO THE USER: 



I active_fnc_err_ 

CALLED BY AN ACTIVE FUNCTION WHEN IT DETECTS AN ERROR 

1 FORMATS AN ERROR MESSAGE MUCH LIKE com err AND THEN SIGNALS 
THE ' active_function - error' CONDITION "" ~" 

I USAGE 

I declare active_fnc_err_ entry options( variable) ; 

I call active_fnc_err_ (code, caller, control string, argj_, 
~ . . . , arg N) ; 

1 THE USAGE IS SIMILAR IN ALL RESPECTS TO com err 
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AN ACTIVE FUNCTION EXAMPLE 



me: proc; 

del cu $af_return arg entry (fixed bin, ptr , fixed bin(21), fixed bin (35)); 

del nargs ~ fixed bin; 

del return arg char (rslength) varying based (rsptr); 

del rsleng"th fixed bin (21); 

del rsptr ptr; 

del code fixed bin (35); 

del user_info_ entry (char (»), char (*), char (*)); 

del (active fnc err_, 

com err_) ~" entry options (variable); 

del error_table_$wrong_no__of_args fixed bin (35) external; 

del person id char (22); 

del project_id char (9); 

del acct char (32); 

/* DETERMINE IF INVOKED AS ACTIVE FUNCTION */ 

call cu_$af return_arg (nargs, rsptr, rslength, code); 
if code *= 
then do; 

call com_err_ (code, "me"); 

return; 
end /* then do */; 

if nargs *s 

then do; „ ... 

call active fnc__err_( error_table_$wrong_no_of__args,"me") ; 

return ; 
end /* then do */; 

/* SO FAR, SO GOOD - GET PERS0N_ID V 

call user info_ (person^id, project__id, acct); 
return__arg = person_id; 

end /* me s /; 
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ACTIVE FUNCTIONS 
AN ACTIVE FUNCTION EXAMPLE 



r 15:19 0.143 

! me 

me: This active function cannot be invoked as a command 
r 15: 19 0.197 5 

! who [me] 
Jackson. MED 

r 15:20 0.524 5 

! who [me Jackson] 
me: Wrong number of arguments supplied. 

Error: Bad call to active function me 
r 15:20 0.206 9 level 2 
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COMMANDS AND ACTIVE FUNCTIONS 



• THE SUBROUTINES DISCUSSED PREVIOUSLY ARE USED IN WRITING PROCEDURES 
THAT MAY BE CALLED AS BOTH COMMANDS AND ACTIVE FUNCTIONS 



THE FOLLOWING SUMMARIZES THE IDIOSYNCRASIES TO BE CONSIDERED IN 
CHOOSING APPROPRIATE SUBROUTINES 



cu_ ENTRY 


COMMAND 


ACT. 
FUNC. 


COMMENTS 


arg_count 


X 


X 


IF INVOKED AS AN ACTIVE FUNCTION 
COUNT INCLUDES RETURN ARGUMENT 


arg_ptr 


X 


X 




af_arg_count 


X 


X 


COUNT EQUALS INPUT ARGUMENTS ONLY 


af_arg_ptr 




X 


NULL arg_ptr IF INVOKED AS A COMMAND 


af_return_arg 


X 


X 


COUNT EQUALS INPUT ARGUMENTS ONLY 
NULL rtn_ptr IF INVOKED AS A COMMAND 



• IT IS ALWAYS POSSIBLE TO WRITE ANY COMMAND OR ACTIVE FUNCTION USING 
ONLY THE TWO ENTRY POINTS, cu_$af_return_arg AND cu_$arg_ptr 
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COMMANDS AND ACTIVE FUNCTIONS 
AN EXAMPLE OF A COMMAND/ACTIVE FUNCTION 



how__long_both: proc; 

del expand_pathname_ entry (char (*) , char (*), char (*) , fixed bin (35)); 

del cu_$arg_ptr entry (fixed bin, ptr , fixed bin(21), fixed bin(35)); 

del cu_$af_return__arg entry( fixed bin, ptr, fixed bin(21), fixed bin (35)1 

del active~fnc_err_ entry options (variable); 

del ncs $status_minf entry (char(*), char(*) , fixed bind), fixed bin(2), 

fixed bin(24), fixed bin(35)); 

del long bit (1) init ( n O"b); 

del arg char (argl) based (argp); 

del complain entry variable options (variable); 

del af bit (1) init ( n 0"b); 

del return_string char (rslength) var based (rsptr); 

del rslength fixed bin (21); 

del rsptr ptr; 

del (i, nargs) fixed bin; 

del argl fixed bin (21); 

del argp ptr ; 

del type fixed bin (2); 

del code fixed bin (35); 

del dir char (168); 

del entry char (32); - 

del (com__err — , ioa_) entry options (variable); 

del ME char""(13) static init ("how long both") options (constant); 

del be fixed bin (24); 

del error__table_$wrong_no_of_args fixed bin(35) external; 

/* check number of args */ 

call cu_$af__return__arg (nargs, rsptr, rslength, code); 

/* command or active function invocation??? */ 

if code s 
then do; 

af s "1 w b; 

complain = active_fnc_err__; 
end /* then do */; ~" 

else complain = com__err__; 

if (nargs < 1) | (nargs > 2) 
then do; 

call complain ( error_table__$wrong_no__of_ args, ME); 

return ; 
end /* then do */; 

/* evaluate args */ 

do i s 1 to nargs; 

call cu_$arg__ptr (i, argp, argl, code); 
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COMMANDS AND ACTIVE FUNCTIONS 
AN EXAMPLE OF A COMMAND /ACTIVE FUNCTION 



/* relative pathname argument */ 

if i s 1 
then do; 

call expand_pathname__ ( arg , dir, entry, code); 

if code *s ""* 

then do; 

call complain (code, ME); 

return; 
end /* then do */; 

call hcs $status_minf (dir, entry, 1, type, be, code); 
if code "*■= 
then do; 

call complain (code, ME); 
return; 
end /* the do */; 
be = bc/36; 
end /* then do */; 
else do; 

/* second arg must be -long or -lg */ 

if (arg = "-long") ! (arg = "-lg") 
then long = "1"b; 
€ X sc do* 

'call complain (0, ME, "Control arg must be -long or -lg") ; 

return; 
end /* else do */; 
end /* else do */; 

end /* do i */; 

if af 
then do; 

return__string = bo; 

return~ 
end /* then do */; 

call ioa_( ""[Number of words for *a>*a is *;~2s~3~i", long, dir, entry, he); 
end /* how long both */; 
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COMMANDS AND ACTIVE FUNCTIONS 
AN EXAMPLE OF A COMMAND/ACTIVE FUNCTION 



r 15:59 0.284 7 

! how_long_both 
how_long~both: Wrong number of arguments supplied. 
r 15:59 0.152 11 

! how_long_both foo -Ig 

how long_both: Entry not found, 
r 1"o":00 0.118 

! how long both how long both 
776"" 
r 16:00 0.076 

! how_long_both how__long_both -long 
Number oT words for >user_dir dir>MED>Jackson>f 15c>how_long_both is 776 
r 16:01 0.098 

! octal [how long both how long both] 
1410 
r 16:01 0.196 6 

! octal [how_long_both] 
how_long_both: Wrong number of arguments supplied. 

r 16:01 0.169 7 level 2 
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OTHER USEFUL SUBROUTINES 



• user info 



RETURNS INFORMATION CONCERNING A USER'S LOGIN SESSION (ALL ARGUMENTS 
ARE OUTPUT ARGUMENTS) 

Q call user_info_ (person_id, projected, acct) ; 



I OTHER ENTRY POINTS: 

I call user_info_$absentee_queue (queue); 

II call user_info_$absentee_request_ id ( request_id) ; 
I call user_info_$absin (path); 

I call user_info_$absout (path); 

I call user_info_$ attributes (attr); 

I call user_info_$homedir (hdir); 

1 call user_ in fo_$ limits (mlim, dim, cdate, crf, shlim, msp, 

csp, shsp) ; 

I call user info $load_ctl_info (group, stby, preempt__time, 

~" weight); "" 

I call user_info $login_arg_count (count, max_length, 

~" ~ to tal — length) ; 

I call user_info_$login_arg_ptr ( arg_no , arg__ptr , arg_len , 
""* ~ code") ; "" 
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OTHER USEFUL SUBROUTINES 

i call uservinfo__ $login__data (person^ id, project_id, acct, 

~" "" "" anon, "stby, weight7 time_login, 

login_word) ; 

11 call user_info_$logout_data (logout_channel , logout^ pid); 

H call user_info_$outer_module (om); 

I call user_info_$process_type ( process_type) ; 

I call tisercin fo__$responder (resp); 

I call user__info_$rs__narae ( rs_name) ; 

I call user_info__$rs__number (rs_number); 

K call user_info_$service_type (type); 

I call user__info_$ terminal_data (id_code, type, channel, 
~" iine_type, charge_type) ; 

I call user_info_$usage_data (nproc, old_cpu, tirae_login, 

time_create , old_mem, 
old_To_cps) ; ~" 

\ call us6r_info_$whoami (person_id, project_id, acct); 
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OTHER USEFUL SUBROUTINES 



value 



READS AND MAINTAINS VALUE SEGMENTS CONTAINING NAME-VALUE PAIRS 
ACROSS PROCESS BOUNDARIES 



I CREATING A VALUE SEGMENT 

I CREATE A SEGMENT WITH A SUFFIX OF .value 



call value_$init_seg ( seg_ptr , seg type, remote_area_ptr 

seg size , cocTe) ; "" 



I DEFAULT VALUE SEGMENT IS [horae_dir3>[ user_narae] .value 
Q call value_ $set_path (path, create_sw, code); 
1 call value_$get_path (path, code); 

1 CREATING AND MAINTAINING NAME-VALUE PAIRS 

I call value_$set ( seg_ptr , switches, name, new_value, 
"" old_value, code); 

I call value $test_and_set ( seg__ptr , switches, name, new_value, 
"~ — — old~value, code); 

I call value_$get ( seg_ptr , switches, name, value__arg, code); 

1 call value $list (set ctr, switches, match info ptr , area ptr , 

vaiue xxsu xniu_pi*i , uuuc/ , 

I call value_$ defined ( seg^ptr , switches, name, code); 
1 call value_$delete ( seg_ptr , switches, name, code); 
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OTHER USEFUL SUBROUTINES 



YOU ARE NOW READY FOR WORKSHOP 



#9 
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WORKSHOP ONE 



Controlled Variables and 'isub 1 Defining 



Write a procedure called 'allocate array. pi 1} that will ask the 
user for the size of one dimensional fixed bin (17) arrays he/she 
wishes to allocate. For example, if the user provides the number 
7, your program is to allocate an array with .7 fixed b _in_ ( 17) 
elements . ' " 

The program should loop f repeatedly asking for the size of the 
next array , ^allocating that array and then initializin g__ all eleme nts.. 
of that array to the current allocation level CTTeTl the first 
array would be initialized to 1 , the second array would be initialized 
to 2, etc.). Use the ' allocat ion' b-uil-fc4a to determine the depth. 

The program should continue allocating and initializing until the 
user responds with zero (0) .. Again using the 'allocation' builtin 
to determine the allocation depth, it should then free all the 
allocated arrays , printing each array just before freeing it . 

Test your program asking for arrays of size 1, 2, 3, and 4. 
Observe the order in which the arrays are freed. 
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2. The segment >udd>MEDclass>F15C>s1>printit .fortran contains a fortran 
subroutine that accepts a 2 by 3 array as an argument and prints 
it out a row at a time. 

Copy the segment, print it, compile it and write a PL/I procedure 
called 'call__fortran.pl1 • declaring a 2 by 3 array and the 3 by 2 
transpose of this array (use isubs) . The program should: 

a. Initialize the 2 by 3 array as follows: 



b. 



c . 



1 
4 



2 

5 



3 
6 



Call the fortran subroutine, passing to it the 
untransposed array. 

Call the fortran subroutine, passing to it the 
transposed array. 



Note : 

1) 'printit' must be declared an entry , and since it 
passed both a 2 by 3 and a "3 by 2 array, its descriptor must 
star convention (dim( *,*)). 



will be 
use the 



2) The e^emgn-ts- of the array should be declared 
since that is^hedata type for fortran integers. 



fix < 



ed bin (35) 



3) The final compilation of the PL/I program will still have a 
"by value" warning since ' isub' defined variables are always passed by 
value. Recall this means that the called procedure will not be able 
to change the variable passed to it. How can this warning be avoided? 
That is, how could the array be passed by reference? 

4) When you compile the PL/I program with the table option (the 
default) , you will receive a warning that the transposed array will 
not appear in the symbol table. 
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WORKSHOP TWO 



Based Variables and Areas 



This workshop has three parts. Be sure you understand the mechanism 
used in parts 1 and 2 (based variables) , since they form the basis for 
workshop three and the remainder of this course. 

1. The following declarations are in the segment 
>udd>MEDclass>F15C>s1>include>w2.incl.pl1 . 

/* Begin w2.incl.pl1 */ 

del string char (10) varying; 

del 1 string parts based (addr (string)), 

2 length fixed bin (35) , 

2 characters char (10); 

del number float binary; 

del 1 float_num based (addr (number)), 

2 sign bit (-1 ) unal , 

2 exponent bit (7) unal, 

2 m_sign bit (1) unal, 

2 mantissa bit (27) unal; 

/* End w2.incl.pi1 */ 

Write a short program that^enters data into the two BASE variables 
X string and number ) and then — prints" out tfre values in ZKe~ BASED 
(overlay) variables in order to see exactly how 'char varying ' and 
' float binary * numbers are stored. (Use put data. ) ~*~~* 

2. Change your working directory to >udd>MEDclass>F15C>s1 . Print the 
segment get_message.pl1 . Execute the corresponding object segment 
and follow the directions given in the message. 

3. In your working directory create an area named AREA (all caps) 
using the create area command. • In the segment, 
>udd>MEDclass>F15C>s1>Fill_area.pl1 , i-s a program that allocates 2 
numbers in that area. Print the program and make sure you understand 
what it is doing. Execute the object segment. Use the dump_segment 
(ds) command to look at your AREA segment. Notice how the pointer 
values printed by the program correspond to locations in the segment. 
Also notice the extra area manager information in the segment. 
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Gaining Direct Access to a Segment 



The segment, >ud d>MEDclass>Fiqc>s1> invoices , contains invoices for a 
number of d i ffeVent v en d o r s . .At the base of the segment is a header. 
The remainder of the segment is a series of linked structures, each 
one representing a single invoice for a particular vendor . The declaration 
to be used for the linked structure is: 

del 1 invoice based ( p) , 

— ' 2 next bit (18) , 

2 invoice__number dec (3)» 

2 vendor_number dec (3) t 

2 charge fixed dec (8,2); 

The structure member, invoice .next , is a non-standard offset (word 
offset from the base of the segment) indicating the location of the 
next structure in the linked list. 

Write a program called ^get_invoices.pl1^ . Your program should prompt. 
the user for a vendor n um~5er~~~"( j aigitsj and then print out all invoice 
numbers and the corresponding cnarges Belonging to that vendor. 

Actually, the segment does not contain just one linked list. There 
are, in fact, 10 linked lists below the header. The header is used to 
determine which list is to be searched for that particular vendor. 
The declaration to be used for the header is: 

del 1 invoice_file header based (seg__ptr), 
""* 2 number_of_Tnvoices fixed bin,"" 

2 hash_table (0:9) bit (18) unal; 

The hash table is made up of 10 non-standard offsets. Each offset 
points to the start of one of the linked lists of invoice structures. 
Which linked list a particular vendor is found in is determined by the 
last digit in the vendor number. For example, invoices for ven dor 35 j , 
would be in the list pointed to by * hash_table(7) ' . ,^-""~" 

Th u s , when a user gives you a vendor number y o u_ must overlay the 
header, structure at the base of the " seamen JL ~a nd jet th e o~ff set.._for th"e~ 
jst'art oj; the appropriat e linked list . Then you must get a p ointer^ to 
>.Ha shart. nfths linked" list! and" move the invoice structu re d own tEe" 
- , TT 3^"irheQkingS ' Q?'--T3^^ vendor. If _t he vendor matches jj^rint^ 

out " the invoice number and tne enarge." Continue scanning EEe list* 
,un~5il you reach the. "end. The l ast~"inv6ice in any list is indicated by 
invoice. next = M n b. 
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As an example, to find invoices for vendor 357, the statement p = 
ptr(seg_ptr,hash_table(7)) would generate a pointer 'p' which locates 
the first invoice for a vendor with low order digit 7. The vendor 
number for this invoice can be compared to 357, and printed out if 
matched. Then, the pointer p could be adjusted to the next invoice in 
this list by coding the statement p a ptr(seg_ptr, p -> next) and so 
oru < " " = """~" ~ 

Test your program by printing out the invoice number and charges of 
all invoices for v endor number 029. ^ 

You may wish to use the following declarations which are in the segment, 
>udd>MEDcl ass >F15C>s1>include>w3.incl.pr i. 

/* Begin w3.incl.pl1 */ 

del initiate file entry (char (*) , char (*), bit (*), pointer, 

fixed bin (24), fixed bin (35)); 
del code fixed bin (35); 

del bit — count fixed bin (24); 

del seg~ptr ptr ; 

del p *~ ptr ;. 

del 1 invoice_file__ header based (seg_ptr), 
2 number_of_Tnvoices fixed bin, 
2 hash_table (0:9) bit (18) unaligned; 

del 1 invoice based ( p) aligned, 

2 next bit (18), 

2 invoice_number dec (3), 

2 vendor_number dec (3), 

2 charge" fixed dec (8,2); 

del com^err^ entry options (variable); 

del ( sysTn , *~ 

sysprint) file; 

/* End w3.incl.pl1 */ 

For the more curious, you may wish to study 
>udd>MEDclas3>F15C>s1>set_up>put_ > invoice.pi1 . 
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The Multics Condition Handling Mechanism 



1. Print the segment >udd>MEDclass>F15C>s1>test_any_other.pl1 (tao.pll) 
and execute the corresponding object segment. 

Examine your user stack using the 'stack' request of 'probe' . 
Notice "where, on the stack, the program you just executed is compared 
to the 'wall' laid down by default error handler. 

Using the 'signal' command, execute the following commands: "signal 
zerodivide", "signal any_other" , "signal finish", "signal 
program interrupt". How do"" you explain the difference in these 
four cases? 

Note: the above program is not well behaved in that it should 
have continued to signal the 'finish' condition. 

BE SURE TO DO A 'release -all' BEFORE PROCEEDING!!! 

2. Print the segment ~>udd>MEDclass>F15C>s1>test__cleanup.pl1 (tcu.pll ) 
and execute the corresponding object segment TWO times. BE SURE 
YOU EXECUTE IT AT LEAST TWO TIMES (more than two won't hurt, but 
is wasteful) . 

Examine the user stack using the 'stack' request of 'probe'. Notice 
the numerous occurrences of 'test cleanup' on the stack. Now examine 
the stack using the ' trace_stack'~(ts) command. Notice the 'cleanup' 
handlers in several stack frames. (While you are at it, also 
notice that 'initialize process_' and ' default_error_handler__' have 
only one condition handler.) 

* Execute a "release -all". Can you explain what happened? 

3. Print the segment >udd>MEDclass>F15C>s1>test_finish_1 .pl1 (tfl.plD 
and execute the corresponding object segment AT LEAST THREE TIMES. 

Signal the finish condition. 

Do a "release -all" and then repeat the above procedure using 
>udd>MEDclass>F15C>s1>test finish 2. pl1 (tf2.pl1). 
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IOCB structure 



1. Print the segment >udd>MEDclass>F15C>s1>examine_iocb.pl1 and read 
it carefully to see what it does. 

2. Execute the pr in t_attach_ table (pat) command to examine the switches 
currently attached. 

3. While in your own directory, execute the following command lines: 

io_call attach zoo vfile_ zoo 
io_call open zoo stream_Joutput 
pat ~~ 

Now execute the program >udd>MEDclass>F15C>s1>examine_iocb and 
carefully examine the results. Notice that all pointers and entry 
points printed are in one of 3 segments. 

4. Recall that the list__reference_names (lrn) command, if given a 
ooomgrif number will return the n athname and reference names of 
that segment. Use this command to determine the three segments 
whose numbers were found in the IOCB. Notice especially which 
entries in the IOCB point to iox__ and which point to the I/O 
module, vfile_. Do these make sense, considering the file is 
opened for stream output? 

5. Execute the command line, * io__call close zoo'. Again execute the 
•pat' command. Run the program, examine__iocb , again and notice 
the different results. Can you explain what happened? If not, 
ask your instructor. 

6. Now that you have looked directly at an iocb using an overlay, 
you should try using the command that gives you the same information. 
Execute the command line ' io__call print_iocb zoo 1 . 

7. Using ' io_call print_iocb <switch>' one can easily look at the 
contents of an iocb. Try the following: delete the segment zoo, 
and then use io_ call to open zoo n keyed_sequential_output" and to 
display the contents of the iocb. ~~ ~" 
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Multics I/O Workshop 



Write a PL/I procedure called (l j. uc ky n um ber . p 1JJ which ^prompt s the 
user for a 6 digit number , and uses that as a key in _fco an indexed file 
of lucky numbers. The file of numbers is in the segment: 

# >udd>MEDclass>F15C>s1>lucky_nos 

The data records a re 32 characters or less in length. 

Display the records. Do not use any language- lev el I/O. Use only 
iox_ and ioa_ calls in your program. 

Test your program with the numbers 780101, 780116, and 771225. 

You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F15C>s1>include>w6.incl .pl1 

V* Begin w6.incl.pl1 */ 

»dcl iox $attach name entry (char (*) , ptr , char (*) , ptr, 

fixed bin (35)); 
del iox_$close entry (ptr, fixed bin (35)); 

,dcl iox""$detach iocb entry (ptr, fixed bin (35)); 
del iox""$open ~ entry (ptr, fixed bin, bit (1) aligned, 

" * fixed bin(35)); 

del iox $read record entry (ptr, ptr, fixed bin (21), 

fixed bin (21), fixed bin (35)) 
del iox $seek key entry (ptr, char (256) varying, 

fixed bin (21), fixed bin (35)) 
del iox $get line entry (ptr, ptr, fixed bin (21), 

fixed bin (21), fixed bin (35)) 
del iox_$user_input external static ptr; 
del (io"a m , 

com™err__) entry options (variable); 

del error_table__$no__record fixed bin (35) external; 
del code "~ fixed bin (35); 

del buff char (32); 

del buff ptr ptr ; 

del rec_Ien fixed bin (21); 

del n_read fixed bin (21); 

del number char (256) varying; 

del cleanup condition; 
del (addr, 

null , 

substr) builtin; 

/* End w6.incl.pl1 */ 
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Be sure that you provide an 

Also, you should check for the 

an invalid key) , after doing the seek_keyT 



on unit 1 for the ' cleanup ' condition. 
*-*"" error__table — $no_record (indicating 
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A Storage System Workshop 



Apply the concepts discussed in Topic Ten by writing a 
called ' new_subsystem.pl 1 ' which, when invoked, will do 



PL /I procedure 
the following: 



1. 



"F15C" 



called 

Jit it d oe s , proceed to 
to <s£ask f">below. ,UL_a 



Determine whether or not a s ubdirector y 

the cal lers .default working directory. 

f'fsfsk ""S^below. If it does not, proceed 

• ^egafpror link called 1! F_15C L W exists in the c al 1 e r ' s ,d e f a ul t worki ng 

directo j^y. delTWunlinkit ^ ngtigy the caller of your action ^ ang- 

proceed to/^S"" 




2.) Since no "F15C" subdirectory exists in the caller's default working 
J directory, create this directory. You should make sure that, besides 
the standard ACL entries, the directory also has an ACL entry 
giving ^ sma" access to Student 01.*.*. Re port the creation of 
this directory to the caller. 




w orking directory to the "F15C" directory, and 



this action. 



Compile and test out your procedure. 



(CONTINUED ON NEXT PAGE) 
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J 
You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F15C>s1>include>w7.incl .pl1 . 



/* Begin w7. incl.pl! */ 



-del 
-del 
"del 

del 

del 
del 
del 
del 
del 

del 
del 
del 
del 



, bit (6), 



char (*) , 
ptr, 



delete $path entry (char (*) , char (*) 

fixed bin (35)); 
hcs__$add_dir acl_entries entry (char (*) , char 
"" - - fi Xec j bi n > fixed bin (35)); 

hcs_$append__branchx entry (char (*) , char (*), fixed bin (5), 
(3) fixed bin (3), char (*) , fixed bin (1), fixed bin (1), 
fixed bin (24), fixed bin (35)); 
hcs_$status_minf entry (char (*) , char (*) , fixed bin (1), 

fixed bin (2), fixed bin (24), fixed bin (35)); 
get_group__id__$tag_star entry returns (char (32)); 

----------- returns (char (168) aligned); 

(char (168), fixed bin (35)); 

(char (*) , char (*), fixed bin (35)) 



get_default_wdir_ 
chang e__wdir~ 
absolute_pathname__ 
(ioa__, 
eom~err_) 

error_table_$nomatch 
error~table_$noentry 
addr 
rings (3) 



entry 
entry 
entry 



del 1 dir_acl aligned, 
2 access__name 
2 dir_modes 
2 status_code 

/* End w7.incl.pl1 */ 



entry options (variable); 

fixed bin (35) external; 

fixed bin. (35) external; 

builtin; 

fixed bin (3) internal static init (4, 4, 4) 

options (constant); 

char (32) init ("Student 01.*.*"), 
bit (36) init ("111"b) , 
fixed bin (35); 
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User Address and Name Space 



1. Write a PL/I procedure called "my ^tmsr .pll "__ that will pr om P fc the 
j jser for a reference name to be„jte_ r~minated _^ "~ Using the appropriate 
j yatry point in term.-. djjp_licaJie_ the action of the 
^terminate ..si nglejr^efname^c^mmand ( t^e . terminate the reference name, 

b ut do" no t ~m ake the segment "unTmown unless it was the last refname 
in the RNT for that segment) . The program should end by notifyi ng 
the user that the terminat ion is complete .^INCLUDE IN THE MESSAGE, 
THE ABSOLUTE PATHNAME OF THT"STeMOT ASSOCIATED WITH THAT REFNAME. 

2. Execute a simple command ( ex . who, memo, pwd , list). Tej3t your 
program using that refer ence name as input . 

3.^-Look at the contents of "*>udd>MEDclass>F 15C>s1>call_sub1 .pl1 and 

=!ff>udd>MEDclass>F15C>s1>sub1 .pl1 . At command level , ""initiate the 

object segment for the first program with the reference name " g.sJ " 

»#{ "initiate >udd>MEDclass>F15C>s1>call_sub1 cs1") . Now execute the 

program bj; simply typing w cs1 ". This", of course, works no matter 

what your working directory is at the time of initiation or execution. 

4.^- Use your "my tmsr" procedure to terminate the reference name"sub1". 
Again execute the call_sub1 program using the name "cs1". It should 
work exactly as it did" before. 
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Writing a Command/ Active Function 



1. Wr ite a pr ocedure c alledQ. parent. pll Q which can function either as 
a/^comm an djSr as a<T"active function It is to return the entrvname 
porlrirnroXthe par efrtrt Kr e ct o r r^Ta segment supplied as an argumen t. 
That is, issuing the command ~ ~~ 

*j parent >udd>MEDclass>F15C>s1>foo 

would result in 's1 * being output to the terminal . Used as an 
active function 

/ [parent >udd>MEDclass>F15C>s1>foo] 

it would r eturn the string 'si'. 

Note of course, the argument needn't be an absolute pathname. 

2. Try your command out on various segments. 

3. Test it's ability to work as an active function by issuing the 
"command : 

status <[ parent ??] 

i-rln av*a *>0 A a *a eArtm An +• i w \m i !*• tjrt *• 1^ w ct A 3 v Art ¥r\v xr 

nilV.4 "w • ■ Jm W CI WVglUCtl W Ail J V >•** »*%■» * tV^iJQ >-4 J.* IvW U"W > j • 

4. Tesjt your program both as a 'command' and as an 'active function 1 
giving it the wrong number of arguments. 
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You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F15C>s1>include>w9.incl.pl1 . 

f * Begin wQ.in o l.pl 1 */ 



del 

del 

del 

del 
del 



del 
del 

del 

del 

del 
del 
del 
del 
del 
del 

del 
del 



cu_$arg__ptr 
cu $af returi 



entry (fixed bin, ptr , fixed bin, 
fixed bin (35)) 
n arg entry (fixed bin, ptr, 
_ ~ ~ fixed bin (35)) 

expand pathname entry (char (*) , char 

fixed bin (35)). 
entry variable options (variable); 



fixed bin (21), 
*) , char (*) , 



complain 

(ioa_, 
com err , 
active_fnc 

error_table 

nargs 

( arg_ptr , 
rtn_string__ 

rtn_string 

arg 

max_length 

arg__len 

code 

af 

ME 

entryname 
dir name 



err ) entry options (variable); 
$wrong_no_of_args external fixed bin (35); 
fixed bin; 

ptr) ptr; 

char (max_length) varying 

based ( rtn_string_ptr) ; 

char (arg__len) based (arg_ptr); 

fixed bin (21); 

fixed bin; 

fixed bin (35); 

bit (1) init ( w 0"b); 

char (6) static init ("parent") 

options (constant); 

char (32); 

char (256); 



^♦-fiS r H yQ.i^l -pi 1 « / 
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